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INTRODUCTION 



WHAT THIS BOOK CONTAINS 

The Prime User' s Guide is an introduction and overview to programming 
in a high-level language on a Prime computer. It contains all the 
information new users need to get started on a Prime system, and 
provides a road map for new and experienced users alike that tells 
what' s available for Prime computers and where to locate information 
about it. 

This guide is divided into four parts. 

Part I contains an introduction (Section 1) , which tells how to use 
this book and provides an annotated guide to Prime's features and 

documentation. 

-\ 

Part II introduces users to PRIMOS (Prime 1 s Operating System) and 
carries them step by step through the acts of creating and running a 
program, as follows: 

• Section 2 introduces Prime's operating system, PRIMOS, and its 
file management system (FMS) . 

• Section 3 tells how to access the system: how to log in; how 
to create, manipulate, list and delete files and directories; 
and how to log out when you're done. 

• Section 4 explains how to enter files (programs, text files, and 
data files) , using Prime's editor; and how to get files printed 
on the line printer. 

• Section 5 provides an introduction to compiling programs under 
PRIMOS. Simple programs can be compiled from the information 
given in this guide. For more complex programs, or programs for 
which the programmer wishes to use the advanced features of 
Prime's compilers, the programmer should consult the specific 
language reference guide. 

• Section 6 provides an introduction to linking and loading 
programs with Prime's two loaders, SEG and LOAD. The 
information in this section enables users to load simple 
programs. The language guides provide information on 
language-specific features; the LOAD and SEG Reference Guide 
provides full information on advanced techniques. 

• Section 7 provides an introduction to executing programs 
interactively. (Language- specific details on execution and 
debugging are provided by your language guide.) 
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• Section 8 tells how to create command files for the 
non- interactive running of programs, how to execute command 
files from the terminal, and how to execute command files as 
phantoms (i.e., as independent processes not connected with your 
terminal) . 

• Section 9 provides full information on how to execute programs 
using Prime's batch processing environment. 

Part III, System Facilities , provides an introduction to the resources 
available on your Prime system. 

• Section 10 tells how to use four file-handling utilities: 

- SORT, which sorts and merges files 

- CMPF, which compares files and notes disparities 

- MRGF, which creates one updated file out of several disparate 
files 

- FUTIL, which moves, copies, lists, and deletes both files and 
complete directories 

• Section 11 explains how to handle magnetic tapes, punched cards, 
and punched paper tapes on Prime. 

• Section 12 explains PRIMENET, Prime's networking facility, and 
tells how users can take advantage of it. 

• Section 13 provides a selected list of important subroutines and 
libraries available for use by high-level language programs. 

Part IV provides a more advanced look at PRIMOS. In particular, it 
duscusses several ways in which you can alter the command environment 
on a term inal-by- terminal or program-by-program basis. 

• Section 14 shows how you can define your own abbreviations for 
PRIMOS commands (via the ABBREV command) and how you can modify 
the system prompts with the RDY command. 

• Section 15 explains PRIMOS' s condition mechanism and shows how 
users can write their own on-units (error-handling subroutines) . 

In addition to the body of the text, this guide provides the following 
appendices: 

• A glossary of terms used in Prime documentation 

• A list of system defaults and constants 
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• The ASCII character set 

• A list of system error messages 

HOW TO USE THIS BOOK 
We suggest that you: 

• Read Sections 1-4 before beginning to work on the system. 

• Read Sections 6-9 before you try to compile, load or run 
programs. 

• Use Sections 10 through 13 as reference sections: 

- Section 10 if you need to sort, compare, or merge files, or 
move whole directories from place to place 

- Section 11 if you need to use mag tapes, cards, or paper tape 

- Section 12 if the computer you work on is part of a network 

- Section 13 to find out whether PRIMOS has a subroutine or 
utility that does some task you need to do, or whether you'll 
have to write your own 

• Read Section 14 when you've become somewhat familiar with the 
system, to discover some more sophisticated conveniences PRIMOS 
can offer you. 

• Refer to the glossary in Appendix A if you encounter any terms 
you don't recognize. 

HOW TO USE THE REST OF PRIME'S DOCUMENTATION 

If this User's Guide provided all the information you'd ever need to do 
anything, it would be about a foot thick. Therefore, Sections 2 
through 14 contain enough information to get you started on just about 
everything. And the rest of this section supplies a road map to all 
our other documentation: the books that do tell you "all you need to 
know." (Titles followed by asterisks document separately priced 
products.) 



January 1980 



SECTION 1 IDR4130 



The Central Guides 

The relationship between these books is illustrated in Figure 1-1. 
This user's guide is the center: the starting place. Backing it up 
are the high-level language guides, which: 

• Provide full language reference materials 

• Explain the compilers in detail, showing the use of all options 

• Explain any language- specific techniques of program development 

• Discuss advanced techniques for loading, optimizing, and 
debugging programs 

Language guides currently available are: 

• The FORTRAN 77 Reference Guide* 

• The FORTRAN Reference Guide 

• The COBOL Reference Guide* 

• The PL/I Subset G Reference Guide* 

• The RPG II Reference Guide (and the RPG II Debugging Template ) 

Mare Detailed References 

The commands and utilities explained in this guide and the language 
guides will carry most applications programmers through most of their 
work. For those who need more detailed references, each topic 
discussed in this book is treated more fully in our reference guides. 
The reference guides that applications programmers are most likely to 
use are: 

• The PRIMPS Commands Reference Guide , which discusses all PRIMOS 
level commands available to the user. 

• The Subroutines Reference Guide , which tells how to incorporate 
into your own programs the various subroutines supplied by 
Prime . 

• The LOAD and SEG Reference Guide , which provides a full 
discussion of Prime's loaders for users interested in taking 
advantage of their advanced features. 

• The Source-Level Debugger Reference Guide ,* which provides both 
introductory and full discussions on the use of Prime's 
interactive debugger for FORTRAN, FORTRAN 77, and PL/I programs. 
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A reference guide for operators and system administrators is: 

• The System Administrator's Guide , which tells how to configure, 
bring up, and maintain a Prime system. 



BASIC 

BASIC is implemented on Prime computers as a fully interactive, 
self-contained environment. Working in BASIC, a progranmer can write, 
compile, execute, and debug a program while remaining inside the BASIC 
environment. Prime's guides to working with BASIC, therefore, are 
similarly self-contained, providing both full explanations of all BASIC 
features and all introductory material needed to get the new user onto 
the system. The guides are: 

• Interpretive BASIC 

• The BASIC/VM Programmer's Guide* 



Assembly Language 

For assembly language programmers, and for anyone interested in 
learning about Prime's computer architecture, there are: 

• The PMA Programmer's Guide 

• The System Architecture Reference Guide 

Prime also supplies a number of guides that deal with more specific 
applications. 

Text Editing 

For users concerned with text editing or formatted printouts, there is: 

• The New User's Guide to Editor and Runoff 

This guide explains in full detail Prime' s editor (ED) and its text 
formatting utility (RUNOFF). (Aimed at users who may not be 
programmers, this guide also provides a less technical introduction to 
Prime software for secretaries, typists and data entry personnel.) 

Data Subsystems 

POWER is an easy-to-use data management system with English-like 
commands that allow the user to create, access, update, and report on 
MIDAS, ASCII, or binary files. 
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POWER files are compatible with (and can be accessed from) BASIC/VM, 
COBOL, and FORTRAN programs. The guide to using POWER is: 

• The PRIME/POWER Guide 

MIDAS - the Multiple Index Data Access System - creates and maintains 
keyed-index data files to hold large amounts of information in a 
quickly accessible format. MIDAS files are handled through a variety 
of high-level language interfaces. Applications programmers working 
with MIDAS files can consult the: 

• Reference Guide / Multiple Index Data Access System (MIDAS) 

FORMS allows applications programmers to design screen formats (such as 
representations of business forms) , to store the formats in a directory 
and to write applications programs that use these screen formats to 
facilitate data entry. The guide that explains how to do it is: 

• The FORMS Guide* 

spss - a statistical package for the social sciences - is useful to 
applications programmers who need statistical tools for data handling. 
The use of SPSS on Prime computers is explained in: 

• The SPSS Guide* 



Data Base Management 

Four guides document Prime's data base management system. Programmers 
writing data base applications programs in FORTRAN or COBOL should 
consult: 

• The DBMS FORTRAN Reference Guide* 

• The DBMS COBOL Reference Guide* 

Data base administrators concerned with setting up and maintaining a 
data base, use: 

• The DBMS Administrator's Guide* 

• The DBMS Schema Reference Guide* 

Communications 

If you are installing a network (or if your installation is on a 
network and you're curious about the details); or if you are writing 
programs concerned with network functions, the guide you want is: 

• The PRIMENET Guide* 
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If your installation has (or is getting) DPTX, (Distributed Processing 
Terminal Executive) and you're involved with it, you'll want: 

• The Distributed Processing Terminal Executive Guide* 

If your work involves any of the main frame emulators - HASP, RJE2780, 
RJE3780, 200UT, 1004, GRTS, or ICL 7020 - you can find out how to 
handle them in: 

• The Remote Job Entry Guide* 

PROGRAMMER'S COMPANIONS 

Prime also provides a series of handy pocket-sized reference summaries 
on many of its products. The following titles are currently available: 

• FORTRAN : The Programmer' s Companion 

• BASIC/VM: The Programmer's Companion * 

• Assembly Language : The Programmer's Companion 

• PRIMPS Commands : The Programmer's Companion 

• System Administrator : The Programmer's Companion 
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SECTION 2 
BEFORE YOU GET STARTED 

INTRODUCTION 

Before you begin using your PRIME computer, you'll need to know: 

• A few facts about PRIME'S operating system, PRIMOS 

• How to define and organize your files and directories using 
PRIMOS 's file management system 

• What the system prompts are 

• What conventions Prime guides use when documenting commands 

• What meaning the special terminal keys have for the PRIMOS 
operating system or for some of its subsystems 

• What meaning some special characters have for PRIMOS or some of 
its subsystems 

• How to define your own special characters or change the 
characteristics of your terminal 

This section explains all of them, in the above order. 

INTRODUCING PRIMOS 

All Prime computers, from the 350 up, use a common operating system 
known as PRIMOS. Under PRIMOS, a Prime computer can support up to 63 
simultaneous users. Each user is totally independent. Each one may 
use any utility (such as an editor or compiler) , and may write, 
compile, load, and execute any program, in any language, without regard 
to what other users are doing on the system. 

Program Environments 

Under PRIMOS, programs may execute in three environments: 

• Interactive 

• Phantom 

• Batch 

Interactive : This is the environment most often used. In it, program 
execution is initiated directly by the user. The terminal is dedicated 
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to the program during execution. The program will accept input from 
the terminal and will print at the terminal any output specified by the 
program as well as user- or system-generated error messages. This 
environment is explained in Section 7. Major uses are: 

• Program development and debugging 

• Programs requiring short execution time 

• Data entry programs such as order entry, payroll, etc. 

• Interactive programs such as the Editor, etc. 

Phantom User : The phantom environment (explained in Section 8) allows 
programs to be executed while "disconnected" from a terminal. Phantom 
users accept input from a command file instead of a terminal; output 
directed to a terminal is either ignored or directed to a file. 

Major uses of phantoms are: 

• Programs requiring long execution time (such as sorts) 

• Certain system utilities (such as line printer spooler) 

• Freeing terminals for interactive uses 

Batch Jobs : Since the number of phantom users on a system is limited, 
phantoms are not always available. The Batch environment (explained in 
Section 9) allows users to sutmit non- interactive command files as 
Batch jobs at any time. The Batch monitor (itself a phantom) queues 
these jobs and runs them, up to six at a time, as phantoms become free. 

Compatibility 

Because a common operating system is used throughout the Prime 
processor line, programs created on one Prime computer can be used on 
most other Prime computers, without modification. There is complete 
upward compatibility among all models, and complete downward 
compatibility among the 750, 650, 550, and 450. Considerable downward 
compatibility exists among other models as well, as long as system 
constraints on program size and mode of code generated are observed. 

Some Hardware Features 

Prime's hardware supports this multi-user, interactive environment with 

• Virtual memory, which allows users to run programs larger than 
the physical memory of the machine. A program may be as large 
as 32 megabytes on the Prime 450 and up (768 kilobytes on the 
Prime 350) . 
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• Segmentation of programs, allowing the separation of code and 
data. This facilitates the creation of pure code for shared or 
recursive procedures. 

• A ring protection system which provides hardware protection for 
the operating system and user subsystems. 

Except for segmentation of large programs, users have little immediate 
concern with these features. They are largely invisible, designed to 
let users concentrate on their own goals without worrying about the 
hardware . 



USING THE FILE SYSTEM 

File and Directory Structures 

A PRIMOS file is an organized collection of information identified by a 
filename. The file contents may represent a source program, an object 
program, a run- time memory image, a set of data, a program listing, 
text of an on-line document, or anything the user can define and 
express in the available symbols. 

Files are normally stored on the disks attached to the computer system. 
No detailed knowledge of the physical location of a file is required 
because the user, through PRIMOS commands, refers to files by name. On 
some systems, files may also be stored on magnetic tape for backup or 
for archiving. 

PRIMOS maintains a separate User File Directory (UFD) for each user to 
avoid conflicts that might arise in assignment of filenames. A Master 
File Directory (MFD) is maintained by PRIMOS for each logical disk 
connected to the system. (A logical disk, sometimes called a volume, 
may occupy either a complete disk pack or a partition of a multi-head 
disk pack. In either case, it serves as PRIMOS 1 s basic unit of 
storage.) The MFD contains information about the location of each UFD 
on the disk. In turn, each UFD contains information about the location 
and content of each file or sub-UFD in that directory. 

The types of files most often encountered are shown in Table 2-1. For 

a description of the PRIMOS file system and a description of the 

ordering of information within files, refer to the Subroutines 
Reference Guide. 



Pathnames 

The PRIMOS file directory system is arranged as a tree. At the root 
are the disk volumes (also called partitions, or logical disks) . Each 
disk volume has an MFD containing the names of several UFDs. Each UFD 
may contain not only files, but subdirectories (sub-UFDs) , and they may 
contain subdirectories as well. Directories may have subdirectories to 
any reasonable level . 
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Table 2-1. Types of Files in PRIMOS 



File 
Type 


Bow 
Created 


Bow 
Accessed 


How 
Deleted 


Use 


ASCII, 
uncompress- 
ed 


Programs 

SORT 

COMOUTPUT 


Programs 

ED (examine only) 

slist, spool 
pl/i stream i/o 
ftn read/Write 


DELETE 
FUTIL DELETE 


Source files, 
text, data 
records for 
sequential 
access 


ASCII, 
Compressed 


ED, SORT, 
Some COBOL 
programs , 


ED, PL/I STREAM 
I/O 


DELETE 
FUTIL DELETE 


Same as un- 
compressed 
ASCII 


variable- 
length 
binary 


FORTRAN WRBIN 
subroutines, 
PL/I record 
I/O, SORT 


FORTRAN RDBIN 
subroutines, 
PL/I record 
I/O 


DELETE 
FUTIL DELETE 


Data records 


Object 
(Binary) 


Translators :RPG, 
FTN, PMA, COBOL, 
PL/I, Binary 
Editor (EDB) 


LOAD or SEG 
Binary Editor 
(EDB) 


DELETE 
FUTIL DELETE 
Binary Editor 


Input to 
SEG or LOAD, 
Libraries 


Saved 

Memory 

Image 


LOAD 

Applications 

programs 


TAP, PSD 
Control panel 


DELETE 
FUTIL DELETE 


Runfiles 


Segmented 
runfile 


SEG 


SEG, VPSD, DBG 
Control panel 


SEG DELETE 
FUTIL TREDEL 


Runfiles 


Segmented 
data file 


SGDR$$ 
subroutine 
MIDAS, DBMS 


SGDR$$ subroutine 

MIDAS 

DBMS 


FUTIL TREDEL 
MIDAS KIDDEL 


Data records 
for direct 
access 


UFD 
Sub-UFD 


CREATE 


Contents: LISTF 


DELETE 
FUTIL TREDEL 


Used by 
PRIMOS 


MFD 


MAKE 


Contents: LISTF 


NO 


Used by 
PRIMOS 


Disk record MAKE 
availabil- 
ity table 
DSKRAT file 


NO 


NO 


Used by 
PRIMOS 


BOOT 


MAKE 


NO 


NO 


Used by 
PRIMOS 


CMDNC0 


MAKE 


Contents: LISTF 


NO 


Used by 
PRIMOS 
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A pathname (also called a treename) is a name used to specify uniquely 
any particular file or directory within PRIMOS. It consists of the 
names of the disk volume, the UFD, a chain of subdirectories, and the 
target file or directory. For example, 

<F0REST>BEECH>BRANCH5>SQUIRREL 

specifies a file on the disk volume FOREST, under the UFD BEECH and the 
sub-UFD BRANCH5. The file's name is SQUIRREL. Figure 2-1 illustrates 
how pathnames show paths through a tree of directories and files. 

Disk volume names, and the associated logical disk numbers, may be 
found with the STATUS DISKS command, described later. A pathname can 
be made with the logical disk number, instead of the disk volume name. 
For example, if FOREST is mounted as logical disk 3, 

<3>BEECH>BRANCH5>SQUIRREL 

specifies the same file as the previous example. 

Usually each UFD name is unique throughout all the logical disks. In 
our example that would mean that there would be only one UFD named 
BEECH in all the logical disks, through 62. When that is the case, 
the volume or logical disk name may be omitted, and PRIMOS will search 
all the logical disks, starting from 0, until the UFD is found. For 
example, if there is no UFD named BEECH on disks 0, 1, or 2, then 

BEECH>BRANCH5>SQUIRREL 

will specify the same file as the previous two examples. This last 
form of pathname, in which the disk specifier is omitted, is called an 
ordinary pathname because it is very frequently used. 

Pathnames vs Filenames 

Ptost commands accept a pathname to specify a file or a directory. So 
the terms "filename" and "pathname" may be used almost interchangeably. 
A few commands, however, require a filename, not a pathname. It is 
easy to tell a filename from a pathname. A pathname always contains a 
">", while a filename or directory name never does. 

Home vs Current Directories 

PRIMOS has the ability to remember two working directories for each 
user: the "home" directory, and the "current" directory. With few 
exceptions, the home and current directories are the same. All work 
can be accomplished while treating them both under the single concept 
of "working directory." 
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PINE1 




PINE2 




BEECH 




PINE3 




ELM 





This directory is the MFD of 
the disk volume <FOREST>. 



(Not all the UFDs 
are shown.) 

^ 















ORIOLE 







This directory is the 
UFD ELM. 



LEAF3 






LEAFS 1 


~ 






LEAF5 

























(Not all subdirectories 
and files are shown.) 















TREEHOUSE 











This is the 

file TREEHOUSE. 




This is the 

subdirectory 

TWIG37. 



This is the 

file SQUIRREL 



This is the 

subdirectory 

TWIG14 



This is the 
file LEAF8. 



This is the 
file LEAF4. 



Figure 2-1. Examples of Files and Directories 
in PRIMOS Tree-structured File System. 
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When the user logs in to a UFD, that UFD becomes the working directory. 
The ATTACH command changes the working directory to any other directory 
to which the user has access rights. A working directory may be an 
MFD, UFD, or sub-UFD. 

The ATTACH command has a home-key option which allows the current 
directory to change while the home directory remains the same. See 
Reference Guide, PRIM03 Commands, for details of this operation. 

Relative Pathnames 

It is often more convenient to specify a file or directory pathname 
relative to the home directory, rather than via a UFD. For example, 
when the home directory is: 

BEECH>BRAISCH5 
the commands 

OK, SLIST BEECH>BRANCH5>TWIG9>LEAF3 
and 

OK, SLIST *>TWIG9>LEAF3 

have the same meaning. The symbol "*" as the first directory in a 
pathname means "home directory." 

Current Disk 

Occasionally it will be necessary to specify a UFD on the disk volume 
you are currently using; that is, where your home directory is. For 
example, when developing a new disk volume with UFD names identical to 
those on another disk, it is necessary to specify which disk is to be 
used, each time a pathname is given. The current disk is specified by: 

<*>BEECH>BRANCH5 

for example. Do not confuse "<*>", meaning current disk, with the "*" 
alone, which means home directory. 



Passwords 

If any directory has a password, the password becomes part of the 
directory name or pathname. Apostrophes are used to enclose the 
pathname. 
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For example, if the directory BEECH had a password, SECRET, a pathname 
using it might be 

•BEECH SECRET>BRANCH5' 



SYSTEM PROMPTS 

The OK Prompt 

The OK prompt indicates that the most recent command to PRIMOS has been 
successfully executed, and that PRIMOS is ready to accept another 
command from the user. The punctuation mark following the "OK" 
indicates to the user whether he is interfacing with a single-user 
level of PRIMOS. The prompt "OK:" indicates single-user PRIMOS (a 
version of PRIMOS II); the prompt "OK," indicates multi-user PRIMOS. 

PRIMOS supports type-ahead . The user need not wait for the "OK," after 
one command before beginning to type the next command. However, since 
each character echoes as the user types it, output from the previous 
command may appear on the terminal jumbled with the command being typed 
ahead. Type-ahead is limited to the size of the terminal input buffer. 
Default is 192 characters. 

PRIMOS II does not support type- ahead . The user must wait for "OK:" 
before entering the next conmand. 



The ER! Prompt 

The ER! prompt indicates that PRIMOS was unable to execute the most 
recent command, for one reason or another, and that PRIMOS is ready to 
accept another command from the user. The ER! prompt usually is 
preceded by one or more error messages indicating what PRIMOS thought 
the trouble was. 

Common errors include: 

• Typographical errors 

• Omitting a password 

• Being in the wrong directory 

• Forgetting a parameter or argument 
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CONVENTIONS 

All of Prime' s user guides and reference guides use a single set of 
conventions for documenting commands. in all of these guides, the 
format of a command will be displayed in the following manner: 

{-option 1 
-option ) [-option] . . . 

The symbols and conventions have the following meanings: 

• W0RD3-IN-UPPER-CASE 

Capital letters identify command words or keywords. They are to be 
entered literally. If a portion of an uppercase word is underlined, 
the underlined letters indicate the minimum legal abbreviation. 

• Words-in-lower-case 

Lowercase letters identify parameters. The user substitutes an 
appropriate numerical or text value. 

• Braces { } 

Braces indicate a choice of parameters and/or keywords. At least one 
choice must be selected. 

• Brackets [ ] 

Brackets indicate that the word or parameter enclosed is optional. 

• Hyphen - 

A hyphen identifies a command line option, as in: SPOOL -LIST. 
Hyphens must be entered literally. 

• Parentheses ( ) 

When parentheses appear in a command format, they must be included 
literally. 

• Ellipsis ... 

The preceding parameter may be repeated. 
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Angle brackets < > 



Used literally to separate the elements of a pathname. For example: 
<F0REST>BEECH>BRANCH537>WIG43>LEAF4 . 



• option 

The word option indicates that one or more keywords or parameters can 
be given, and that a list of options for the command follows. 



• Spaces 

Command words, arguments and parameters are separated in command lines 
by one or more spaces . In order to contain a literal space, a 
parameter must be enclosed in single quotes. For example, a pathname 
may contain a directory having a password: 

"<FOREST>BEECH SECRET>BRANCH6 ' . 

The quotes ensure that the pathname is not interpreted as two items 
separated by a space. 

User input usually may be either in lowercase or in uppercase. The 
rare exceptions will be specified in the commands where they occur. 



SPECIAL TERMINAL KEYS 

• CONTROL 

The key labeled CONTROL (or CTRL) charges the meaning of alphabetic 
keys. Holding down CONTROL while pressing an alphabetic key (or some 
special keys) generates a control character. Control characters do not 
print. Some of them have special meanings to the computer. (See 
CONTROL-P, CCNTROL-Q and CONTROL-S, below.) 

• RUBOUT 

The key labeled RUBOUT has a special use in Prime's text processing 
utility, RUNOFF. It is not generally meaningful to other standard 
Prime software. On some terminals it is labeled DELETE or DEL. 



• RETURN 

The RETURN key ends a line. PRIMOS modifies the line according to any 

erase (") or kill (?) characters, and either processes the line as a 

PRIMOS command, or passes it to a utility such as the EDITOR. RETURN 
is also called CR, CARRIAGE-RETURN, or NEW-LINE. 
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• BREAK 
ATTN 
INTRPT 



See CONTROL-P 



SPECIAL CHARACTERS 
• Caret (~) 

Used in EDITOR to enter octal numbers and for literal insertion of 
special characters. On some terminals and printers, prints as up-arrow 
(t) . 



• Backslash (\) 

Default EDITOR tab character. 

• Double-quote (") 

Default erase character for PRIMOS and all subsystems. Each 
double-quote erases a character from the current line. Erasure is from 
right (the most recent character) to left. Two double-quotes erase two 
characters, three erase three, and so forth. You cannot erase beyond 
the beginning of a line. The PRIMOS command TERM (described later in 
this section) allows the user to choose a different erase character. 

• Question mark (?) 

Default kill character for PRIMOS and all subsystems. Each question 
mark deletes all previous characters on the line. The PRIMOS command 
TERM allows the user to choose a different kill character. 

• CONTROL-P 

QUIT immediately (interrupt/terminate) from execution of current 
command and return to PRIMOS level. Echoes as QUIT. Used to escape 
from undesired processes. Will leave used files open in certain 
circumstances. Equivalent to hitting BREAK key. 

• CONTROL-S 

Halt output to terminal, for inspection. Program will run until output 
buffer is full; then it will be suspended. Any commands other than 
CONTROL-S or CONTROL-Q will be placed in the input buffer (until that 
buffer is full) . They will not execute until the suspended program has 
terminated. Input will not be echoed at the terminal until either 
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CONTROL-P (QUIT) or CONTROL-Q (Continue) is given. This special 
function is activated by the command TERM -XOFF. 



• CONTROL-Q 

Resume output to terminal following a CONTROL-S (if TERM -XOFF is in 
effect) . 



• UNDERSCORE (J 

On some devices, prints as a backarrow (-*-) . 



• RESERVED CHARACTERS 

The following characters are reserved by PRIMOS for special uses, 
may not be used in file names: 



They 



(){}[]<>! 



= + 



@ ~ 



? " \ " rubout 



SETTING TERMINAL CHARACTERISTICS 

Terminal characteristics may be set with the TERM command. These 
characteristics remain in effect until you reset them or until you log 
out. The commonly used TERM options are listed below. Typing TERM 
with no options returns the full list of TERM options available. The 
format is: 

TERM options 

The common options are: 

Option Function 

-ERASE character Sets user's choice of erase character in 

place of the " default. 

Sets user's choice of kill character in 
place of ? default. 

Enables X-OFF/X-ON feature, which allows 
users to suspend terminal output 
temporarily and to resume it at the point 
of suspension. Output is halted by typing 
CONTROL-S and is resumed by typing 
CONTROL-Q. Also sets terminal to full 
duplex (default value) . 



-KILL character 



-XOFF 



REV. 



- 12 



IDR4130 BEFORE YOU GET STARTED 

Option Function 

-NOXOFF Disables X-OFF/X-ON feature (default) . 

-DISPLAY Returns list of currently set TERM 

characters. Also displays current Duplex, 
Break and X-ONA-OFF status. 
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SECTION 3 
ACCESSING PRIMOS 



INTRODUCTION 

In this section we introduce the essential PRIMOS commands so that you 
can begin working on the system. We recommend that you keep a 
Programmer's Companion handy as a summary of the commands explained in 
this section plus other FRIMOS commands. In this user's guide we have 
selected only those PRIMOS commands we know will be of use to most 
programmers. Depending upon your application, there are many other 
PRIMOS commands that may simplify your task or increase efficiency. 

Using PRIMOS 

PRIMOS recognizes more than 100 commands, some of which invoke 
subsystems which themselves respond to subcommands or extensive 
dialogs. However, most users can do 99 percent of their program 
development using about a dozen commands. This section introduces the 
essential commands needed by all users. These commands allow you to: 

• Gain admittance to the computer system (LOGIN) 

• Change the working directory (ATTACH) 

• Create new directories for work organization (CREATE) 

• Secure directories against intrusion (PASSWD) 

• Remove empty directories or unwanted files (DELETE) 

• Examine the location of the working directory and its contents 
(LISTF) 

• Look at the availability and current usage of system resources - 
space, users, etc. (AVAIL, STATUS, USERS) 

• Rename files or directories (CNAME) 

• Determine file size (SIZE) 

• Examine files (SLIST) 

• Remove unneeded files (DELETE) 

• Allow controlled access to files (PROTEC) 

• Complete a work session (LOGOUT) 
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ACCESSING THE SYSTEM 



In order to access or work in the system, the user must first follow a 
procedure known as 'login'. 'Logging in' identifies the user to the 
system and establishes the initial contact between system and user (via 
a terminal) . Once logged in, the user has access to a working 
directory (work area) , to files and to other system resources. The 
format of the LOGIN command is: 

LOGIN ufd-name [password] [ -ON nodename] 

ufd-name The name of your login directory. 

password Must be included if the directory has 

a password. 

-ON nodename Used for remote login across PRIMENET network. 

For example: 

LOGIN DOUROS NIX 

DOUROS (21) LOGGED IN AT 10'33 112878 

The number in parentheses is the PRIMOS-assigned user number (also 
called 'job' number). The time is expressed in 24-hour format. The 
date is expressed as mmddyy (Month Day Year) . The word NIX, in this 
example, is the password on the login directory. 

During login, a misspelled UFD will cause the message "Not found. 
(LOGIN)" to be displayed. A misspelled or incorrect password will 
return the message "Insufficient access rights. (LOGIN)." If you get 
either of these messages, check to be sure you're logging into the 
right directory with the right password; then try logging in again. 
If you still have trouble, ask your supervisor for help. If the system 
itself is overloaded, a message such as "maximum number of users 
exceeded" may be displayed. In this case, log in again later, when 
some other user may have logged out. 

DIRECTORY OPERATIONS 

Changing the Wbrking Directory 

After logging in, the user's working directory is set to the login UFD 
by PRIMOS. The user can move (i.e., attach) to another directory in 
the PRIMOS tree structure with the ATTACH command. The format is: 

ATTACH new-directory 

new-directory is the pathname of the new working directory. 
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Note 



If any directory in the pathname has a password, the pathname 
must be enclosed in single quotes, as in: 

A 'BEECH SECRET>BRANCH5' 

To set the MFD of a disk as the working directory, the format is 
slightly different: 

ATTACH <volume>MFD mfd-password 

volume is either the literal volume name or the logical disk number, 
and mfd-password is the password of the MFD. A password is always 
required for an MFD. 

Recovering from Errors While Attaching : If an error message is 
returned following an ATTACH command (for example, if a UFD is not 
found) , the user remains attached to the previous working directory. 

However, if an incorrect password is given, then the user is not 
attached to any UFD (has no working directory). If a command, such as 
LISTF, is entered while in this state, the message: 

NO UFD ATTACHED 

is returned. To remedy this condition, the user must ATTACH to a UFD 
as in: 

A BEECH 

or to a subdirectory, using a complete or ordinary pathname (but not a 
relative pathname) , as in: 

A BEECH>BRANCH2 



Creating New Directories 

To organize tasks and work efficiently, it is often advantageous to 
create new sub-UFDs. These sub-UFDs can be created within UFDs or 
other sub-UFDs with the CREATE command. They can contain files and/or 
other subdirectories. The format is: 

CREATE pathname 

The pathname specifies the directory in which the sub-UFD is being 
created, as well as the name of the new directory. For example: 

CREATE <1>T0PS>MIDDLE>B0TT0M 

The sub-UFD BOTTOM is created in the sub-UFD MIDDLE, which in turn is 
found in the UFD TOPS, which is in the MFD of disk volume 1. 
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Subdirectories may be created within the current directory simply by 
specifying the new directory name. For example: 

CREATE SUBDIR 

Two files or sub-UFDs of the same name are not permitted in a 
directory. If this is inadvertently attempted, PRIMOS will return the 
message: 

Already exists. DIRECTORYHtfAME 
ER! 



Assigning Directory Passwords 

Directories may be secured against unauthorized users by assigning 
passwords with the PASSWD command. There are two levels of passwords: 
owner and non-owner. If you give the owner password in an ATTACH 
command, you have owner status; if you give the non-owner password in 
an ATTACH command, you have non-owner status. Files can be given 
different access rights for owners and non-owners with the PROTEC 
command (see Controlling File Access) . 

The PASSWD command replaces any existing password (s) on the working 
directory with one or two new passwords, or assigns passwords to this 
directory if there are none. The format is: 

PASSWD owner-password [non-owner-password] 

The owner- password is specified first; the non-owner- password , if 
given, follows. If a non-owner password is not specified, the default 
is null; then, any password (except the owner password) or none allows 
access to this directory as a non-owner. For example: 

OK, A DOUROS NIX 
OK, PASSWD US THEM 

The old password, NIX, is replaced by the owner password US, and the 
non-owner password THEM. Passwords may contain almost any characters; 
but they may not begin with a digit (0-9) . 



Examining Contents of a Directory 

After logging in or attaching to a directory, the user can examine the 
contents of this directory with the LISTF command which generates a 
list of the files and subdirectories in the current directory. The 
format is: 

LISTF 
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For example, the working directory is called EAURA. The following list 
will be generated when LISTF is entered at the terminal : 

OK, LISTF 

UFD=<MISCEL>TEKMAN>LAURA 6 OWNER 

$QUERY BOILER EX LETTER QUERY OLISTF BASICPROGS 

OUTLINE $OUTLINE MQL $MQL $LETTER MQL. LETTER FTN10 

EXAMPLES FUTIL.10 $FUTIL.10 

OK, 

The number following the UFD-name is the logical device number, in this 
case, 6. The words OWNER or NONOWN follow this number, indicating the 
user status in this directory. (See Assigning Directory Passwords ) . 

If no files are contained in a directory, .NULL, is printed instead of 
a list of files. 



Deleting Directories 

When directories or subdirectories are no longer needed, they may be 
removed from the system to provide more room for current work. If the 
directories are empty, they may be removed by the DELETE command. The 
format is: 

DELETE pathname 

If an attempt is made to delete directories containing files or 
subdirectories, PRIMOS prints the message: 

The directory is not empty. (DIRECTORY-NAME) 

In this case, the user must do one of two things: 

• Use the LISTF command to find what files (or subdirectories) are 
in the directory. Delete each entry with the command "DELETE 
filename." Then delete the empty directory. 

• Use FUTIL's TREDEL command (explained in Section 10) to delete 
files and directory simultaneously. 



SYSTEM INFORMATION 



Table 3-1 summarizes useful information you may need about the system 
and how to obtain it. 
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Table 3-1. Useful System Information 



Item 
Number of users 

User login UFD 

User number 

User line number 

User physical 
device 

Open file units 
Magnetic tape units 

Disks in operation 

Assigned peripheral 
devices 

User priorities 

Other user numbers 

Your phantom 
user number 

Network information 

Current nodename 
Records available 



System time 
and date 



Use 

Indicates system 
resource usage and 
expected performance. 

Identifies user who 
spooled text file 
(printed on banner) . 



Avoids conflict when 
using files. 

Lists assigned units, 
with their logical 
aliases and users 



Tells what devices 
are available. 



Fbr legging out your 
phantoms. 

Tells if network is 
available. 



Tells how much room 
is available for file 
building, sorting, etc. 

Performs time logging 
in audit files. 



PRIMPS commands 

STATUS USERS (user list) 
USERS (number of users) 



STATUS, STATUS UNITS, 
STATUS ME 



STATUS ME, STATUS USERS 
STATUS ME, STATUS USERS 
STATUS ME 

STATUS, STATUS UNITS 

STATUS DEVICE 

STATUS, STATUS DISKS 
STATUS USERS 

STATUS USERS 
STATUS USERS 
STATUS USERS, STATUS ME 

STATUS, STATUS NET 

STATUS NET, STATUS UNITS 
AVAIL 

DATE 
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Item 



Table 3-1. (Cont'd) 



Use 



PRIMOS commands 



Computer time used Measures program 
since login execution time. 



Spool queue 
contents 



Tells if job has been 
printed. 



TIME 



SPOOL -LIST 



Names and status of Tells if local printers PROP -STATUS 



printers 

Environment for a 
printer 

Batch users 



Your active Batch 
jobs 

Batch queue status 

Batch queue 
configurations 



are functioning. 

Gives parameters for 
printer's operations 

Identifies executing 
jobs, number of jobs 
per queue 

Gives job id, status; 
gives job parameters 



Shows environment 
of Batch system 

Note 



PROP printer-name 
-DISPLAY 

BATCH DISPLAY 



JOB -STATUS 
JOB -DISPLAY 

BATGEM -STATUS 

BATGEN -DISPLAY 



Information given by any STATUS command is also given by the 
STATUS ALL command. 
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FILE OPERATIONS 

Creating and Modifying Files 

Text files are created and modified using the text editor (ED). They 
are printed on the line printer using the SPOOL command. Both these 
processes are discussed in Section 4. Files may be transferred from 
other systems not connected via PRIMENET using magnetic tape (MAGNET 
command) , paper tape (ED command) , or punched cards (CRSER command) . 
These commands are described in Section 11. 



Changing File Names 

It is often convenient or necessary to change the name of a file or a 
directory. This is done with the CNAME command. The format is: 

CNAME old-name new-name 

old-name is the pathname of the file to be renamed, and new-name is the 
new filename. For example: 

en tools>more_test oldtest 

The file named MORE_TEST in the UFD TOOLS is changed to OLDTEST. Since 
no disk was specified, all MFDs (starting with logical disk 0) are 
searched for the UFD TOOLS. 

If new-name already exists, PRIMOS will display the message: 

Already exists. OLDTEST 
ERJ 

An incorrect old-name prompts the message: 

Not found. MORETEST 
ER! 



Determining File Size 

The size (in decimal records) of a file is obtained with the SIZE 
command. This command returns the number of records in the file 
specified by the given pathname. The number of records in a file is 
defined as the total number of data words divided by 440. However, a 
zero-word length file always contains one record. The format is: 

SIZE pathname 
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For example: 

OK, SIZE GLOSSARY 

14 RECORDS IN FILE 



Examining File Contents 



Contents of a program or any text file can be examined at the terminal 
with the SLIST command. The format is: 

SLIST pathname 

The file specified by the given pathname is displayed at the terminal. 
It is possible to suspend the terminal display as it is printing. See 
the discussion on TERM, in Section 2. 



Deleting Files 

When files or programs are no longer needed they may be removed from 
the system to provide more room for other uses. The DELETE command 
deletes files from the working directory. The format is: 

DELETE pathname 

SEG runfiles cannot be deleted by this command. They must be deleted 
by SEG's own delete command (explained in Section 5) or by FUTIL's 
TREDEL command (explained in Section 10) . 



Controlling File Access 

Assigning passwords to directories allows users working in a directory 
to be classified as owners or non-owners, depending upon which password 
they use with the ATTACH command. Controlled access can be established 
for any file using the FROTEC command. This command sets the 
protection keys for users with owner and non-owner status in the 
directory. (See Assigning Directory Passwords above.) The format is: 

PROT EC pathname [owner- rights] [non-owner-rights] 

pathname The name of the file to be protected. 

owner- rights A key specifying owner's access rights to 

file (original value = 7) . 

non-owner- r ights A key specifying the non-owner's access 

rights (original value = 0) . 
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The values and meanings of the access keys are: 

Key Rights 

No access of any kind allowed 

1 Read only 

2 Write only 

3 Read and Write 

4 Delete and truncate 

5 Delete, truncate and read 

6 Delete, truncate and write 

7 All access 

For example: 

PROTEC <OLD>MYUFD>SECRET 7 1 

In this example, protection rights are set on the file SECRET in the 
UFD MYUFD so that all rights are given to the owner and only read 
rights are given to the non-owner. 

Note 

The default protection keys associated with any newly created 
file or UFD are: 7 0. The owner is given ALL rights and the 
non-owner is given none. Default values for the PROTEC 
command, however, are: 0. Thus, the command PROTEC MYFILE 
denies all rights to owner and non-owner alike. 

COMPLETING A WORK SESSION 

When finished with a session at the terminal, give the LOGOUT command. 
The format is: 

LOGOUT 

PRIMOS acknowledges the command with the following message: 

UFD-name (user-number) LOGGED OUT AT (time) (date) 
TIME USED = terminal-time CPU-time I/O-time 

user-number The number assigned at LOGIN. 

terminal-time The amount of elapsed clock time between LOGIN 
and LOGOUT in hours and minutes. 
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CPU-time Central Processing Unit time consumed in minutes 

and seconds. 

I/O- time The amount of input/output time used in minutes 

and seconds. 

It is a good practice to log out after every session. This closes all 
files and releases the PRIMOS process to another user. However, if you 
forget to log out, there is no serious harm done. The system will 
automatically log out an unused terminal after a time delay. This 
delay is set by the System Administrator (the default is 1000 minutes 
but most System Administrators will lower this value) . 
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SECTION 4 
CREATING SOURCE FILES 

ENTERING AND MODIFYING PROGRAMS - THE EDITOR 

Programs are normally entered into the computer using Prime' s Text 
Editor (ED). This Editor is a line-oriented text processor. That is, 
it enters and modifies text on a line-by-line basis, keeping track of 
its current location by a line pointer which is always located at the 
last line processed (whether the processing action is printing, 
locating, moving pointer, etc). The Editor operates in two modes, 
INPUT and EDIT. 

Using the Editor 

When creating a new file, the Editor is invoked by 
ED 

which places the Editor in the INPUT mode. When modifying an existing 
file, the Editor is invoked by 

ED filename 

which places the Editor in the EDIT mode. 

A RETURN with no preceding characters on that line switches the Editor 
from one mode to another. 

Input Mode 

The INPUT mode is used when entering text information into a file 
(e.g., creating a program). The word INPUT is displayed at the user's 
terminal to indicate that the Editor has entered that mode. The RETURN 
key terminates the current line and prepares the Editor to receive a 
new line. Tabulation is done with the backslash (\) character. Each 
backslash represents the first, second, etc., tab setting; the default 
tabs are at columns 6, 15, and 30. These settings may be overridden 
and up to 8 tab settings may be specified by the user with the TABSET 
command (described later) . A RETURN with no text preceding it puts the 
Editor into EDIT mode. 

Edit Made 

The EDIT mode is used when the contents of the file are to be modified. 
More than 50 commands are available, although users will find that a 
small subset of these will suffice for most purposes. The commands are 
listed and described later in this section. 
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In EDIT mode, the Editor maintains an internal line pointer at the 
current line (the last line processed) . Commands such as TOP, BOTTOM, 
FIND, and LOCATE, move this pointer. WHERE prints out the current line 
number; POINT moves the pointer to a specified line number. The MODE 
NUMBER command causes the line number to be printed out whenever a line 
of text is printed. All commands for location and modification begin 
processing with the current line. 

A RETURN without any preceding characters puts the Editor into the 
INPUT mode. 



Special Characters 

In either mode, a single character can be erased with the erase 
character (default is ") . For each " typed, a character is erased 
(from right to left) . The entire current line may be deleted by typing 
the kill character (default is ?) . A line followed by a ? is null, 
and a RETURN at that point will switch the Editor into the other mode. 

In input mode, the semicolon (;) is equivalent to a CR (ends a line of 
input) . In edit mode, semicolons in a character string are treated as 
a printing character; semicolons within commands separate multiple 
commands entered on the same line. A special character may be entered 
literally in either mode by preceding it with an escape character O . 
Special characters may be changed using the TERM command (explained in 
Section 1) . 

Saving Files 

Orderly termination of an Editor session is done from EDIT mode. The 
command : 

FILE filename 

writes the current version of the edited file to the disk under the 
name filename . The specified file will be created if it did not 
previously exist or overwritten if it does exist. If an existing file 
is being modified, the command 

FILE 

writes the edited version to the disk with the old filename. After 
execution of the filing command, control is returned to PRIMOS. 
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Useful Techniques 

The following will aid the user in adapting to Prime's Editor: 

Tab Settings ; When entering source code, much time can be saved using 
the TABSET command, in INPUT mode, each \ character is interpreted as 
one tab setting; the default values are columns 6, 15, and 30. Tabs 
may be set to whatever values each programmer finds useful. Setting a 
tab near column 45 makes entry of in-line comments simple; the use of 
such comments in programs is strongly advised. 

Moving Lines of Code ; Any number of lines can be moved from one 
location to another using the DUNLOAD command. DUNLOAD deletes these 
lines as it writes them into an auxiliary file. A LCAD command loads 
the new file at the desired point. Any number of lines can be copied 
from one location in a program to another using the UNLOAD command . 
UNLOAD does not delete the lines as it writes them into an auxiliary 
file. A LCAD command loads the copy from the new file at the desired 
point. 

Overlaying Comments After Code is written ; Comments may be easily 
added to an existing source program with the OVERLAY command in 
conjunction with the TABSET command. 

Finding a Line by Label or Statement Number ; The FIND command may be 
used to locate a statement number in a FORTRAN program or a label in a 
COBOL or PL/I program. 

Modifying a Line Without Changing Character Positions ; The MODIFY 
command is used when a line must be modified but the absolute column 
alignment must remain the same. 

Other hints; When entering FORTRAN programs, it is often helpful to use 
the TABSET command to reset tabs to columns 7 and 45. 

When entering PL/I programs, use the SYMBOL command to change the 
SEMICO character (which normally tells the editor of the end of a line 
or command) from a semicolon to something else. For example: 

SYMBOL SEMICO { 

In this example, the brace becomes the Editor's line-ending symbol, and 
the semicolon is freed for its PL/I functions. 

To enter a single semicolon (or other special character) , precede it 
with an up-arrow. 

To enter up-arrows literally, type two up- arrows. The result displays 
as two up-arrows on the terminal, but prints as one up-arrow on the 
printer and is interpreted as a single up-arrow by compilers. 
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SAMPLE EDITING SESSIONS 

Here are three examples showing the writing and editing of source 
files. See the list following these examples for an explanation of the 
commands. 



A PL/I Example 

OK, ED 
INPUT 



EDIT 

TABSET 3 6 9 12 18 21 

SYMBOL SEMICO [ 



INPUT 

\PO 1=1 TO 10 

\\PO J=l fO~T0; 

\\\X(I,J=A(I)+B(I); 

XXXYq^SQRTtxq^J)); 

WEND; /*J-L0OP*/ 

\END; /*I-LOOP*/ 



An empty line puts us in edit mode 

Set tabs for PL/I code 

Change editor's delimiter symbol 

Empty line puts us in input mode 

Type in source code using tabs 
to show levels of indentation 



EDIT 

TOP 

NEXT 

DO 1=1 TO 10 
APPEND ; 

DO 1=1 TO 10; 
NEXT 2 

X(I,J=A(I)+B(I); 
CHANGE/J/J) 



X(I,J)=A(I)+B(I); 
TOP 

PRIT 7PRINT 99 
.NULL. 
DO 1=1 TO 10; 
DO J=l TO 10; 

X(I,J)=A(I)+B(I); 
Y(I,J)=3QRT(X(I,J)); 
END; /*J-LO0P*/ 
END; /*I-LOOP*/ 
BOTTOM 
FILE ED. EX 



Go to top of file 
First non-null line 

Add a forgotten semicolon 

Down two lines 

Balance parentheses 

Check code before filing 



Name a new file when you file it 



OK, 
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A FORTRAN Example 

OK, ED 
INPUT 

EDIT 
TABSET 7 45 

INPUT 

\A-"=30V* COMMENT 

\B=40 

C-A?\C=A+B 

\PRINT 10 ,C 

CALL EXTI""IT 

\END 

EDIT 

FILE FTN.TEST 



Useful settings for FORTRAN 



Quote mark erases one character 



Question mark erases entire line. 



OK, ED FTN.TEST 
EDIT 
PRINT 20 
.NULL. 

A=30 /* COMMENT 

B=40 

C=A+B 

PRINT 10, C 

CALL EXIT 

END 
BOTTOM 
NEXT -3 

PRINT 10, C 
TABSET 7 45 

INSERT 10\FORMAT('THE ANSWER IS', 14) 
TOP, PRINT 20 
.NULL. 

A=30 /* COMMENT 

B=40 

C=A+B 

PRINT 10, C 
10 FORMAT ('THE ANSWER IS ',14) 

CALL EXIT 

END 
BOTTOM 
FILE No need to use a filename this time 



Move up three lines 

Set FORTRAN tabs again 
Insert forgotten line 
Check file once more 



OK, 
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A COBOL Example 



OK, ED 
INPUT 



EDIT 

MODE COLUMN 

INPUT 

12 3 4 5 6 7 
1234567890123456789012345678901234567890123456789012345678901234567890123456789 

ID DIVISION. 

PROGRAM-ID. TEST. Source coding is keyed in, 

INSTALLATION. PRIME. aligned by column. 



\ 



The first tab default is position 
6. A space after the backslash 
character positions the asterisk 
in the continuation column 7. 



OK, 



EDITOR COMMAND SUMMARY 

The following is an alphabetic list of each Editor command and its 
function. Acceptable command abbreviations are underlined. Especially 
useful commands are indicated with a bullet (•) . For a detailed 
description of all commands, see the Editor Reference Section of The 
New User's Guide To EDITOR and RUNOFF. 

Note 



The string parameter in a command is any series of ASCII 
characters including leading, trailing, or embedded blanks. A 
semicolon terminates the command unless it appears within 
delimiters (as in the CHANGE, MODIFY, or GMODIFY commands) or 
is preceded by the escape character (") . 



Command 



Function 



• APPEND string 



• BOTTOM 



Appends str ing to the end of the 
current line. 

Moves the pointer beyond the last 
line of the file. 
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BRIEF 



• CHAN3E/string-l/string-2/[G] 



Speeds editing by suppressing the 
(default) verification responses to 
certain Editor commands. 

[n] Replaces string-1 with string-2 for 
n lines. If G is omitted, only the 
Tirst occurrence of string-1 on each 
line is changed; if G is present, 
all occurrences on n lines are 
changed. 



• DELETE [n] 
DELETE TO string 

• DUN LOAD filename [n] 

DUNLOAD filename TO string 

ERASE character 

• FILE [filename] 

FIND string 

• FIND(n) string 
GMODIFY 



Deletes n lines, including 
current line (default n=l) . 



the 



Deletes all lines up to but not 
including line containing str ing ♦ 

Deletes n lines from current file 
and writes them into filename. 
(Default n=l.) 

Same as DELETE. ..TO, but writes 
deleted lines into filename . 

Sets erase character to character . 

Writes the contents of the current 
file into filename and QUTTs to 
FRIMOS. 

Moves the pointer down to the first 
line beginning with str ing . 

Moves the pointer down to first line 
with str ing beginning in column n. 

Allows the user to enter a string of 
subcommands which modify characters 
within a line. 



INPUT 



(ASR) 
(PTR) 
(TTY) 



Reads text from the specified 
input device: ASR (Teletype 

paper-tape reader) , PTR (high-speed 
paper tape reader) or TTY 
(terminal) . Default is TTY. 



• INSERT string 
KILL character 



Inserts string after current line. 
Sets kill character to character. 
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LINESZ [n] 

LOA D filename 
JJOCATE string 

LOCATE string, ^ 

MODE CKPAR 
MODE COLUMN 



Changes maximum line length. 
(Minimum linesz is 10) . Linesz 
changes the maximum length of both 
command lines and input lines. 

Loads filename into text following 
the current line. 

Moves pointer forward to the first 
line containing string, which may 
contain leading and trailing blanks. 

Moves pointer forward to each 
occurrence of string between 
pointer's current position and end 
of file. 

Prints characters as real characters 
if parity's on, as octal numbers 
Cnnn) if parity's off. 

Displays column numbers whenever 
INPUT mode is entered. 



MODE COUNT start increment width < 



PRINT \ 

BLANK \ 

k SUPPRESS j 



MODE 


NCKPAR 


MODE 


NCOLUMN 


MODE 


NCOUNT 


MODE 


NUMBER 


MODE 


NN UMBER 


MODE 


PRALL 



Turns on the automatic incremented 
counter. 

Prints all characters as if they had 
parity on (default) . 

Turns off the column display 
(default) . 



Suspends counter 
(default) . 



incrementing 



Displays line numbers in front of 
printed line. 

Turns off the line number display 
(default) . 



Prints lower case characters 
device has that capability. 



if 
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MODE PRUPPER 



MODE PROMPT 



Prints all characters as upper case. 
Precedes lover case characters with 
an ~L and precedes upper case 
characters with an ~U if the device 
is upper case only. 



Prints prompt characters 
and EDIT modes. 



for INPUT 



MODE N PROMPT 



M0DIFY/string-2/string-l/[G] [n] 



Stops printing of INPUT and 
prompt characters (default) . 



EDIT 



Superimposes string-1 onto string-2 
for n lines. If G is omitted, only 
the "First occurrence of string-1 on 
each line is modified; otherwise 
all occurrences of string-1 are 
modified. 



MOVE buffer-l|buffer-2| 
l/string/| 



Move string or contents 
of buffer-2 into buffer-1. 



NEXT [n] 



Moves the pointer n lines forward or 
backward (default n=l) . 



NFIND string 



NFIND(n) string 



Moves pointer down to first line NOT 
beginning with str ing . 

Moves pointer down to first line in 
which string does not start in 
column n. 



• OVERLAY string 



PAUSE 



Superimposes string on current line. 
Use tabs to start in middle of line, 
use ! to delete existing 

characters. (A blank in the string 
leaves the old character in place.) 



Returns to operating system 
changing the Editor state. 



without 



POINT line-number 



Relocates the pointer 

1 ine-number . 



to 



• PRINT [n] 



PSYMBOL 



Prints the current line or n lines 
beginning with the current line. 
Moves pointer to last line printed. 

Prints a list of current symbol 
characters and their function. 
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PTABSET tab-l...tab-8 



Provides for a setup of tabs on 
devices that have physical tab 
stops. 



PUNCH 



QUIT 



( ASR ) 
(PTP) 



[n] 



RETYPE string 



SYMBOL name character 



TABSET tab-l...tab-8 

• TOP 

• UNLOAD filename [n] 
UNLOAD filename TO string 

• VERIFY 

WHERE 
XEQ buffer 



Punches n lines on high- or 
low-speed pa par- tape punch. 

Returns control to PRIMOS without 
filing text. 

The current line is replaced by 
string . 

Changes a symbol name to character . 
Current default values are: 



Name 

KILL 

ERASE 

WILD 

BLANK 

TAB 

ESCAPE 

SEMICO 

CPRCMPT 

DPROMPT 



Default Characters 
? 

i 

# 
\ 



$ 
& 



Sets up to eight logical tab stops 
to be invoked by the tab symbol ( ) . 

Moves the pointer one line before 
the first line of text. 

Copies n lines into filename . 

Unloads lines from current file into 
filename until str ing is found. 

Displays each line after completion 
of certain commands. (Default) . 

Prints the current line number. 

Executes the contents of buffer. 
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^[n] Causes preceding command to be 

repeated n times as in: 

F /;D;*10 

which deletes the next ten lines 
that begin with / . If n is 
omitted , the command repeats until 
the bottom of file is reached. 



LISTING PROGRAMS 

Terminal Listing 

Source programs may be listed at the terminal by using the SLIST 
command, described in Section 3. 

Line Printer Listing 

Use the SPOOL command (explained below) to obtain a copy of a source 
file on the system line printer. 

Renaming 

Programs may be renamed with the PRIM03 command CNAME (Section 3). You 
must have owner status in the UFD in order to use this command. 

Deleting 

Programs may be deleted with the PRIMOS command DELETE (Section 3) . 
You must have delete access in order to use this command. 



OBTAINING COPIES OF FILES (SPOOL) 

Printed copies of files from a line printer are obtained with the SPOOL 
command. It has several options, some of which will not apply to all 
systems, as systems may be configured differently. The format is: 

SPOOL pathname [options] 
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PRIMOS makes a copy of pathname in the Spool Queue List for the line 
printer, and displays the message: 

Your spool file, PRTnnn, is x record [s] long. 

nnn is a 3-digit number which identifies the file in the Spool Queue 
List, x is nunber of records in the file. PRIMOS spools out short 
files as soon as possible; long files receive a lower priority. For 
example : 

OK, spool example 
[SPOOL rev 17.2] 
Your spool file, PRT015, is 2 records long. 

OK, spool tekman>alice> update 

[SPOOL rev 17.2] 

Your spool file, PRT016, is 1 record long. 

OK, 

In this example, one file was spooled by filename and the other by 
pathname. However, SPOOL will refer to both by their filenames, that 
is, EXAMPLE and UPDATE. 

Checking the Queue ; To check the status of the Spool Queue, give the 
command: 

SPOOL -LIST 

PRIMOS returns a list of all the files on the Queue which have not yet 
been printed. Additional information, such as the size, destination, 
the PRT number, any options, the form-type and the login-name of the 
user who spooled the file, are also specified. For example: 



OK, spool -list 
[SPOOL rev 17.1] 

user prt time name size opts/If form defer at: NEWTON 



ELLEN 001 16:42 CARLSON . REPFIL 

TEKMAN 002 9:19 COB#01 

TEKMAN 003 9:20 COB#02 

SCELZA 005 9:20 TIMEJTABLE.MEM 

SCELZA 006 9:20 TIMEJTABLE.MEM 

SCELZA 007 9:20 TIMEJTABLE.MEM 

TEKMAN 008 9:21 GORK 

OK, 



40 


2 WIDE 




3 


3 


22:00 





WHITE 


18:00 


4 


WHITE 




4 


WHITE 




4 


WHITE 




6 




18:00 
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Cancelling a Spool Request ; To cancel one or more spool requests, the 
command format is: 

SPOOL -CANCEL [PRT]n-l [,n-2...] 

where n-1 , n-2 , etc., are the numbers of your spool files to be 
cancelled. For example: 

OK, spool -cancel 47 048 prt049 
[SPOOL rev 17.0] 
PRT047 has been cancelled. 
PRT048 has been cancelled. 
PRT049 has been cancelled. 

Printing Multiple Copies : You can request several copies of one file 
by using the -COPIES option: 

SPOOL pathname -COPIES n 

n is the number of copies desired. 

Deferring Printing : The -DEFER option tells the Spooler not to begin 
printing the indicated file until the system time matches the time 
specified with DEFER. This permits you to enter SPOOL requests at your 
convenience, rather than waiting for the appropriate hour. 

Specify the DEFER option by: 

SPOOL pathname -DEFER time 

The format for time is HH [:] MM [AM/PM] . If AM or PM is given, HH:MM 
(the colon is optional) must be in 12-hour format (e.g., 1000 pm) . 
Otherwise, time will be interpreted as 24-hour format (in which 2200 is 
10:00 PM and 1000 is 10:00 AM) . 

Printing on Special Forms : Line printers traditionally use one of two 
types of paper — "wide" listing paper, on which most program listings 
appear, and 8-1/2 x 11-inch white paper, which is standard for memos 
and documentation. Computer rooms often stock a variety of special 
paper forms for special purposes, such as 5-copy sets, pre-printed 
forms (checks, orders, invoices) , or odd sizes or colors of paper. 

Request a specific form by: 

SPOOL pathname -FORM form-name 

form-name is any six-character (or less) combination of letters. A 
list of available form names can be obtained with the PROP command, 
explained in the PRIMOS Commands Reference Guide. 
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Changing the Header ; The -AS option tells the spooler to print your 
file under a different name. The form is: 

SPOOL pathname -AS alias 

The alias will appear on the header and in the SPOOL -LIST display. 

Printing at Specific Locations ; Networks with several printers often 
arrange to have the printers read each other's queues. It is therefore 
possible for a spool request to be printed at another location, perhaps 
many miles distant. To insure that a spool request is printed where 
you want it, use the -AT option: 

SPOOL pathname -AT destination 

destination is a word of 16 letters or less. A list of available 
destination-names can be obtained with the PROP command, explained in 
the PRIMOS Commands Reference Guide. (If a destination appears in the 
heading of the SPOOL -LIST display, for example, AT:NEWTON, then that 
destination is the default destination for spool requests. If no 
destination folows "AT:", then no default has been established, and 
spool requests without destinations may be intercepted by any available 
printer. 

Eliminating Headers : To have files printed without header or trailer 
pages, use the -NOHEAD option: 

SPOOL pathname -NOHEAD 

This option is particularly useful with preprinted forms, but if you're 
using this option in a multi-user environment, you will have to 
identify your own jobs. 

Multiple Options : Any or all of the above options may be used jointly 
in a single SPOOL command line. If -LIST or -CANCEL is included, it 
must be the last option on the command line. For example: 

OK, spool o_17 -as ex.1 -at bldg.l -defer 22:00 

[SPOOL rev 17.0] 

Your spool file, PRT048, is 1 record long. 

This particular command requests that the file named "0_17" be printed 
at the "bldg.l" printer, under the alias of "EX.1", at 10 pm (22:00). 

PRINTING SEVERAL FILES IN ONE (CONCAT) 

The CONCAT command concatenates files into a single file, which can 
then be printed via the SPOOL command. The format for CONCAT is: 

CONCAT new-file-name [-options] 
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Options govern the format of the print-out and the disposition of the 
files. For details, see CONCAT in the PRIMOS Commands Reference Guide. 

When you give the CONCAT command without options, CONCAT goes into 
input mode. It asks for the names of the files to be concatenated, and 
prints a colon prompt. Type the filenames, one per line. A null line 
(carriage return) signals the end of list. CONCAT then goes into 
command mode, and prints a right-angle prompt. You can then type a 
QUIT to end the session. (You can also type "INPUT" to return to input 
mode; or you can give various formatting commands, explained in the 
PRIMOS Commands Reference Guide.) 

A sample session might be: 

OK, concat triplet 
[CONCAT Rev 17.0] 

Enter filenames, one per line: 
: first 
: second 
: third 
: (CR) 

OK, 

If the file TRIPLET already exists, CONCAT asks: 

OK to modify old TRIPLET? 

Answering NO returns you to PRIMOS command level. Answering YES 
prompts a second question: 

Overwrite or append? 

Answering OVERWRITE causes CONCAT to replace the old TRIPLET with a new 
one. Answering APPEND preserves the existing contents of TRIPLET and 
adds the new ones at its end. 
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After the source code has been entered into the system, it must tie 
compiled. Compilation creates a new file of linkable code, the object 
(or binary) file. Each high-level language has its own compiler which 
creates object code from source code. At the object code level, these 
languages are equivalent. Thus, modules of object code originating 
from different source language may be linked together to form a 
run-time program. (Further comments on this will be found at the end 
of this section.) Details of Prime's compilers are treated in the 
individual language user guides. This section will consider features 
common to all compilers. 

INVOKING THE COMPILER 

The compiler is invoked from PRIMOS-command level by the command: 

compiler pathname [options] 

compiler is the compiler for the language in which the source program 
is written. Current compilers are: 

Compiler Language 

COBOL COBOL 

F77 FORTRAN 77 

FTN FORTRAN IV 

PL1G PL/I Subset G 

RPG RPG II 

pathname is the pathname of the source program file. 

options allow specification of the creation of object and listing 
files, the mode in vtfiich the object code is to be generated, the types 
of cross references and listings to be generated, debugger interfaces 
and the like. These options may be common to all compilers or unique 
to a particular language. The common options are summarized in Table 
5-1 and discussed in the following paragraphs. 
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Table 5-1. Compiler Defaults 



Compiler 


Binary/ 

Object 
File 


Listing 
File 


Cross- 
Reference 


Mode 


COBOL 


yes 


yes 


no 


64V 


F77 


yes 


no 


no 


64V 


FTN 


yes 


no 


no 


32R 


PL1G 


yes 


no 


no 


64V 


RPG 


yes 


yes 


yes 


64R 


Comments 


default 
B filename 


default 
L filename 


use 

-XREF 

option 





OBJECT FILES 

In all compilers, the default is to create an object file. The default 
name of this file is B filename. For example, suppose the source file 
is TEKMAN>EXAM>TEST. If" this file were compiled, the default object 
file would be B_TEST in the working directory. A non-default binary 
file can be created (or suppressed) with the -BINARY option 
(abbreviation -B) . Possible arguments for this option are: 



Argument 
-BINARY YES 
-BINARY NO 
-BINARY pathname 



Meaning 
Create binary file with default name 
Do not create binary file 
Create binary file called pathname 
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LISTING FILES 

Each compiler can create a file listing the source program. 
Language-specific options are available to expand on these listings and 
add more information. The standard listing is generated by default for 
all compilers except FTN and F77. The option to create a listing file 
is -LISTING (abbreviation -L) . The default name, which is formed in 
the same way as the default object file name, is L filename. The 
arguments for the -LISTING option are: "" 

Argument Meaning 

-LISTING YES Create listing file with default name. 

-LISTING NO Do not create listing file. 

-LISTING pathname Create listing file called pathname . 

-LISTING TTY Print listing file at terminal. 

-LISTING SPOOL Print listing file on line printer. 

CROSS REFERENCE 

Each language has its particular cross reference listing. Each lists 
the program's variables, tells where they appear in the program, and 
provides other useful information. Specific details are in each 
language guide. Cross references are listed by default for RPG only. 
In other languages, the cross-references listing is generated by using 
the option -XREF in the command line. 



CODE GENERATION 

The addressing mode in which object code is to be loaded must be chosen 
at compilation time. Prime's compilers can generate object code to be 
loaded in several addressing modes. Table 5-2 shows which types of 
code can be generated by each compiler. 
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Table 5-2. Code Generation 





321 


625V 


64R 


32R 


FORTRAN 77 (F77) 


/ 


/ 






FORTRAN IV (FTN) 




/ 


/ 


/ 


PL/I Subset G 


/ 


/ 






COBOL 




/ 






RPG 






/ 





In general, 64V mode is the mode of choice. This is the default on all 
compilers except FORTRAN IV (FTN) and RPG II (RPG). At present, the 
RPG compiler generates only 64R mode code. Tb generate 64V mode code 
in FORTRAN IV, use the 64V option in the command line. For example: 

FTN GOOD -LISTING YES -64V 

compiles the program GOOD, producing 64V mode code and creating a 
listing file, L GOOD. 

The FORTRAN 77 (F77) and PL/I (PL1G) compilers can also generate 321 
mode code. 321 mode code handles double-precision floating-point 
arithmentic more rapidly than the other modes do. Therefore, it is the 
mode of choice for many mathematical calculations. To generate 321 
mode code, use the 321 option in the command line, as in: 

F77 CHEERS -321 



LOADING 

All code generated in 64V or 321 mode is loaded with SEG. (This 
procedure is often called linking on other systems.) Code generated in 
32R or 64R mode is loaded with LOAD. These loaders (or linkers) are 
summarized in Section 5, and explained in detail in the LOAD and SEG 
Guide. 



COMPILER MESSAGES 

If a compilation completes successfully, a message to that effect is 
printed at the user's terminal (or into the user's comoutput file, if 
the compilation is not interactive. See Section 7 for information on 
comoutput files.) If compilation is not successful, error and/or 
warning messages will indicate the offending line and the offense. 
Some severe errors halt the compilation as soon as they are discovered. 
Others allow the compilation to proceed. Each compiler has its own 
error messages. 
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Error messages printed by the F77 and PL1G compilers include 
explanatory comments. Error messages generated by the FIN, COBOL, and 
RPG compilers are discussed in those language guides. 



COMBINING LANGUAGES IN A PROGRAM 

Since all high-level languages are alike at the object code level, and 
since all use the same calling conventions, programs compiled by the 
FTN, F77, COBOL, or PL1G compilers can call subroutines compiled by any 
of the other three compilers. For example, a program written in COBOL 
could call a subroutine written in FORTRAN 77 which might use a utility 
subroutine written in PL/I-G. Procedures compiled by the high-level 
language compilers may also call, or be called by, procedures written 
in Prime's assembler language, PMA. The following cautions, however, 
should be observed: 

• All I/O routines should be written in a single language. 

• Be sure that there is no conflict in data types for variables 
being passed as arguments. For example, an integer in FORTRAN 
should be declared as fixed binary in PL/I. Also, remember that 
PL/I and COBOL may not interpret structures identically. 

• All procedures within a program must use compatible addressing 
modes. Do not put R-mode procedures into a V-mode or I-mode 
program, or vice versa. (V-mode and I-mode are compatible 

within programs.) 

• Some special restrictions must be observed when FTN and F77 
routines are linked together. These are discussed in the 
FORTRAN 77 Language Guide. 
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LOADING PROGRAMS 



INTRODUCTION 

PRIMOS has two utilities for loading programs: SEG and LOAD. SEG 
loads (and runs) V-mode and I-mode programs; LOAD loads R-mode 
programs. This section explains the basic use of SEG and LOAD for 
programs written in high-level languages. Language- specific aspects of 
loading programs are treated in the individual language guides. The 
loaders are explained in detail in the LOAD and SEG Reference Guide. 



SEG 

The PRIMOS SEG utility converts object modules (such as those generated 
by the FTN, F77, COBOL, and PL1G compilers) into segmented runfiles 
that execute in the 64V addressing mode and take full advantage of the 
architecture and instruction set of the Prime 350 and up. Segmented 
runfiles offer the following advantages: 

• Much larger programs: up to 256 segments per user program (32 
Megabytes) 

• Access to V-mode instructions and architecture (Prime 350 and 
up) for faster execution 

• Ability to install shared code: a single copy of a procedure 
can service many users, significantly reducing paging time 

• Re-entrant procedures permitted: procedure and data segments 
can be kept separate 

The following description emphasizes the commands and functions that 
are of most use to high-level language programmers. Extended features, 
as well as a complete description of all SEG commands, including those 
for advanced system-level programming, are described in the LOAD and 
SEG Reference Guide. 



USING SEG UNDER PRIMOS 

SEG is invoked by PRIMOS command: 

SEG [pathname] 

A pathname is given only when an existing SEG runfile is to be 
executed. (See Section 7.) Otherwise, the command transfers control 
to SEG command level, which prints a "#" prompt character and awaits a 
SEG command. After executing a subcommand successfully, the loader 
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repeats the prompt character. (SEG's loader prints a $ prompt to 
request its subcommands.) 

If an error occurs during an operation, SEG prints an error message, 
then the prompt character. Error messages and suggested handling 
techniques are discussed in this section and in Appendix D. 

When a system error (File in use, Illegal name, Insufficient access 
rights, etc.) is encountered, SEG prints the system error and returns 
the prompt symbol. 

SEG remains in control until a QUIT subcommand returns control to 
PRIMOS, or an EXECUTE subcommand starts execution of the loaded 
program. 

SEG subcommands can be used in command files, but comment lines are 
accepted only within its LOAD subprocessor. 



NORMAL LOADING 

Loading is normally a simple operation with only a few straightforward 
commands needed. (SEG has many additional features to optimize runfile 
size or speed, perform difficult loads, load for shared procedures, and 
deal with possible complications. These are described in the LOAD and 
SEG Reference Guide.) 

The following commands (shown in abbreviated form) accomplish most 
loading functions. 



SEG-Level Commands 

DELETE Deletes segmented runfile. 

HELP Prints a list of SEG commands at terminal. 

LOAD Invokes loader subprocessor for entry of subcommands. 

LOAD Subcommands 

LOAD pathname Loads specified object file. 

LIBRARY [filename] Loads library object files from UFD LIB. 

(Default is PFTNLB and IFTNLB) 

MAP [option] Prints loadmap. Option 3 shows unresolved 

references (usually subroutines which have not 
been loaded) . Mapping is explained in the LOAD 
and SEG Reference Guide. 
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INITIALIZE Returns loader to starting condition in case of 

command errors or faulty load. 

SAVE Saves loaded memory image as r unfile. 

RETURN Returns to SEG command level. 

QUIT Return to PRIMOS. 

Most loads can be accomplished by the following basic procedure: 

1. Invoke SEG from PRIMOS level. 

2. Enter the LOAD command to initiate the loading process. 

3. Use the LOAD subcommand to load the object file (B_filename) 
and any separately compiled subroutines. 

4. Use the LIBRARY subcommand to load subroutines called from 
libraries. 

5. If you do not receive a LOAD COMPLETE message, do a MAP 3 to 
identify the unsatisfied references, and load them. If the 
unsatisfied references are the result of having misspelled some 
subroutine names, you may want to initialize and re-do the 
load. 

6. SAVE the runfile. 

If these commands produce a LOAD COMPLETE message, then loading was 
accomplished. If there is a problem, it will become apparent by the 
absence of a LOAD COMPLETE message or some other SEG error message. 
(See Appendix D for a complete list of all SEG error messages and their 
probable cause and correction.) 

After a successful load, you can either start runfile execution from 
loader command level, or quit from the loader and start execution 
through the PRIMOS RESUME command. An example of such a load is: 



OK, SEG 

[SEG REV 17.1] 

# LOAD 

SAVE FILE TREE NAME: #BENCH9 

$ LP B,BENCH9 

$ LI 

LOAD COMPLETE 

$ SA 

$ QU 

OK, 
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Order of Loading 

The following loading order is recommended: 

1. Main program 

2. Separately compiled user-generated subroutines (preferably in 
order of frequency of use) 

3. Language- specific libraries (PL1GLB for PL/I, VCOBLB and 
possibly NCOBLB for COBOL) 

4. Other Prime Libraries (LI filename) , such as VAPPLB (V-mode 
applications library) , VSRTLI (V-mode sort library) , VDKALB 
(MIDAS library) 

5. Standard PRIME library (LI) 

For example, a COBOL program which uses MIDAS files would be loaded as 
follows: 

OK, SEG 

[SEG REV 17.1] 

# LOAD #MAIN 



$ LOAD B.MAIN 
$ LOAD B-SUBR 
$ LI VCOBLB 
$ LI NCOBLB 

$ LI VKDALB 

$ LI ~ 

LOAD COMPLETE 
$ SAVE 
$ QUIT 
OK, 



Main program first. 

Separately compiled subroutine next. 

Shared COBOL library: always used. 

Non-Shared library: used with separately-compiled 

subroutines 

MIDAS library: used with MIDAS files. 

Standard (FORTRAN) library. 

Save the file image 

Return to PRIMOS command level. 



THE R-MODE LOADER 

The PRIMOS LOAD utility converts object modules (such as those 
generated by the FTN or RPG compilers) into runfiles that execute in 
the 32R or 64R addressing modes. (Runfiles to execute in the 64V mode 
must be loaded using the segmentation utility, SEG.) 

The following description emphasizes the loader commands and functions 
that are of most use to the FORTRAN and RPGII programmer. Por a 
complete description of all loader commands, including those for 
advanced system-level programming, refer to Reference Guide, LOAD and 
SEG. 
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USING THE LOADER UNDER PRIMOS 

The PRIMOS command: 

LOAD 

transfers control to the R-mode loader, which prints a $ prompt 
character and awaits a loader subcommand. After executing a command 
successfully, the loader repeats the $ prompt character. 

If an error occurs during an operation, the Loader prints an error 
message, then the $ prompt character. Loader error messages and 
suggested handling techniques are discussed elsewhere in this section 
and in Appendix A. Most of the errors encountered are caused by large 
programs where the user is not making full use of the Loader 
capabilities. 

When a system error (File in use, Illegal name, Insufficient access 
rights, etc.) is encountered, the loader prints this system error and 
returns its prompt symbol, $. 

The loader remains in control until a QUIT or PAUSE subcommand returns 
control to PRIMOS, or an EXECUTE subcommand starts execution of the 
loaded program. 

Load subcommands can be used in command files, but comment lines result 
in a CM (command error) message unless they are preceded by ' * 



■ 



NORMAL LOADING 

Loading is normally a simple operation with only a few straightforward 
commands needed. The loader also has many additional features to 
optimize runfile size or speed, perform difficult loads, and deal with 
possible complications. The most frequently used load commands and 
operations are presented first; this enables immediate use of the 
loader. Advanced features are then described followed by a summary of 
all loader commands. 

The following commands (shown in abbreviated form) accomplish most 
loading functions. 



PRIMOS-Level Commands 

FILMEM Initializes user space in preparation for load. 

LOAD Invokes loader for entry of subcommands. 

RESUME Starts execution of a loaded, SAVEd runfile. 
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LOAD Subcommands 



DC 



MODE option 



LOAD pathname 



Defers loading of COMMON until everything else 
has been loaded. This presents overlap of 
COMMON and program areas. 

Sets runfile addressing mode as D32R (default) 
or D64R. 



Loads specified object file. 



LIBRARY [filename] Loads library object files from UFD 

(Default is FTNLIB.) 



LIB. 



MAP [option] 



INITIALIZE 



Prints loadmap. Option 3 shows unresolved 
references. 

Returns loader to starting condition in case of 
command errors or faulty load. 



SAVE pathname 
QUIT 



Saves loaded memory image as runfile. 
Return to PRIMOS. 
Most loads can be accomplished by the following basic procedure: 

1. Use the PRIMOS FILMEM command to initialize memory. 

2. Invoke LOAD. 

3. Use the MODE command to set the addressing mode, if necessary. 
(The default is 32R mode.) 

4. Use loader's LOAD subcommand to load the object file 
(B_filename) and any separately compiled subroutines. 

5. Use loader's LIBRARY subcommand to load subroutines called from 
libraries (the default is FTNLIB in the UFD LIB). Other 
libraries, such as SRTLIB or APPLIB, must be named explicitly. 

6. If you do not have a LOAD COMPLETE, do a MAP 3 to identify the 
unsatisfied references, and load them. (If the DC option is 
used, the LOAD COMPLETE message may not appear until the SAVE 
command has been given.) 

7. SAVE the runfile under an appropriate name. 

If these commands produce a LOAD COMPLETE message, then loading was 
accomplished. If there is a problem, it will become apparent by the 
absence of a LOAD COMPLETE message or some other loader error message. 
(See Appendix D for a complete list of all loader error messages and 
their probable cause and correction.) 



REV. 



IDR4130 LOADING PROGRAMS 



After a successful load, you can either start runfile execution from 
LOAD command level, or quit from the loader and start execution through 
the PRIMOS RESUME command. An example of such a load is: 



OK,FILMEM 

OK, LOAD 

$ DC 

$ LP B_BENCH9 

$ LI 

LOAD COMPLETE 

$ SA *BENCH9 

$ QU 

OK, 



Order of Loading 

The order of loading, procedures for mapping, etc., are the same for 
LOAD as they are for SEG. 



V January 1980 



IDR4130 RUNNING PROGRAMS INTERACTIVELY 



SECTION 7 
RUNNING PROGRAMS INTERACTIVELY 

INTRODUCTION 

This section treats the following topics: 

• Execution of segmented runfiles saved by SEG's Loader 

• Execution of program memory images saved by the R-mode Loader 

• Run-time error messages 

EXECUTING SEGMENTED RUNFILES 

For programs loaded and saved by SEG, execution is performed at the 
PRIMOS command level using the SEG command: 

SEG pathname 

vtfiere pathname is the name of a SEG runfile. SEG loads the runfile 
into segmented memory and starts execution. SEG should be used for 
runfiles created by SEG's loader; it should not be used for program 
memory images created by the R-mode loader. Example: 

OK, SEG #TEST user requests program 

THIS IS A TEST output of program 

OK, PRIMOS requests next command 

Upon completion of program execution, control returns to PRIMOS command 
level. 

A SEG runfile may be restarted by the command: 
S 1000 

if both the SEG runfile and the copy of SEG used to invoke it are in 
memory. 

EXECUTING R-MODE MEMORY IMAGES 

For programs loaded in 32R or 64R mode by the loader, execution is 
performed at the PRIMOS level using the RESUME command. Programs which 
are already resident in the user's memory may be executed by a START 
command. 
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RESUME pathname 

RESUME brings the memory- image program pathname from the disk into the 
user* s memory, loads the initial register settings, and begins 
execution of the program. For example: 

OK, R *TEST User requests program 
THIS IS A TEST Output of program 

OK, PRIMOS requests next command 

Note 

RESUME should not be used for segmented (64V mode) programs. 
Use the SEG command (discussed in the first part of this 
section) instead. 

The Start Command 

If a program has been made resident in memory (for example, by a 
previous RESUME command) , 

START [start-addressl 

the command may be used to initialize the registers and begin 
execution. 

START can also restart a program that has returned control to PRIMOS 
(for example, because of an error, a FORTRAN PAUSE or CALL EXIT 
statement) . If START is typed without a value for start-address , the 
program resumes at the address value at which execution was 
interrupted. To restart the program at a different point, specify an 
octal starting location as the start-address value; the usual default 
value for the beginning of FORTRAN programs is 1000. For example: 

OK, R *TEST1 Begin 

INPUT NEW KEY: 5 Program asks for input 

QUIT User hit BREAK to stop 

OK, S 1000 Restart program from beginning 

INPUT NEW KEY: 

The applications programmer will almost always use the default forms of 
the RESUME and START commands (the form discussed here) . For a 
complete treatment of these commands, see the Reference Guide, PRIMOS 
Commands. 

Upon completion of the program, control returns to PRIMOS command 
level. 
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RUN-TIME ERROR MESSAGES 



During program execution, error conditions may be generated and 
detected by the FORTRAN mathematical functions, file system subroutine 
calls, or the operating system. A list of run-time error messages is 
given in Appendix D. 

Error messages specific to execution of segmented programs are labeled 
64V mode. Some error messages imply system problems beyond the scope 
of the applications programmer. if so, this is indicated in the 
explanation of a given error message. 
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SECTION 8 
COMMAND FILES AND PHANTOMS 



COMMAND FILE OPERATIONS 



PRIMOS offers three utilities that allow command sequences to run from 
files rather than from direct user interaction. They are: 

• COMINPUT 

• PHANTOM 

• JOB 

COMINPUT reads commands from a specified file. Commands and responses 
appear on the user's terminal. The terminal is dedicated to this 
operation during execution. 

PHANTOM reads commands from a file but executes as another PRIMOS 
process, freeing terminal for other use. Limited number of phantom 
processes are available, so user may have to wait for a free process. 

JOB reads commands from a file, but executes as a phantom. Users 
submit jobs at their convenience; the Batch monitor queues them and 
runs them, one to six at a time, as phantoms become free. (Batch 
replaces CX and accepts all existing CX command files.) 

All of these utilities read commands from a command file, which is a 
file containing PRIMOS commands, utility subcommands, and dialog 
responses. The user creates the file with the Editor, runs it under 
COMINPUT to verify operation, edits it to make charges, and thereafter 
runs it under COMINPUT, PHANTOM or Batch. This is particularly useful 
for long program development operations that must be repeated whenever 
source code is changed, building libraries, production job runs, etc. 

Supporting the three command processing utilities is the COMOUTPUT 
command which maintains an audit file of the dialog between PRIMOS and 
the user or command file. Output generated by the command file can 
thus be channeled to the COMOUTPUT file, to be printed, edited, or 
listed at the terminal (via SLIST) whenever the user wishes. 

The date of execution, time of execution, and time consumed during 
execution of the command file can be placed in the output file by 
including the DATE, TIME, or RDY -LONG commands in the command file. 

This section discusses: 

• How to create and run command files 

• How to have command files call each other 
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• How to create COMOUTPUT files 

• How to use DATE, TIME, and RDY in command files 

• How to run command files as phantoms 

Batch execution of command files will be discussed in the next section. 

COMMAND FILE REQUIREMENTS 

Command input files may contain any legal PRIMOS commands, utility 
subcommands, or dialog responses, on a line-for-line basis (i.e., each 
line in the file must correspond to a line as it would be typed at a 
terminal.) Each utility except Batch imposes certain requirements: 

• For COMINPUT, the last command should be COMINPUT -TTY or 
COMINPUT -END. 

• Fbr PHANTOM, the last command should be LOGOUT. 

• Any command file can be used for Batch. 

Comments 

Command input files can be made self-documenting by including comment 
lines at PRIMOS command level. A line beginning with a slash and 
asterisk, (/*) , is interpreted as a comment and is ignored by PRIMOS. 
If a command output file is open, any comments entered at the terminal 
by the user or from a command file are written into the command output 
file. Any character may be used in a comment line. A comment may also 
be appended to a command at PRIMOS command level as in: 

SLIST M_BENCH07 /* PRINT MAP FILE 

THE COMINPUT COMMAND 

The COMINPUT command causes PRIMOS to read input from a specified 
command file rather than from the terminal. Commands are executed as 
if they were entered at the terminal. The format is: 

COMINPUT [command- file] [-options] [file-unit] 

command- file The pathname of the file from which input is to 
be read. 

options Specify command control flow as detailed below. 
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file- unit The PRIMOS file unit number on which the input 
file is to be opened, if omitted, file unit 6 
is used. File units must be octal (i.e., 
decimal 8 is entered as 10) . 



Options 

-TTY Either one switches the command input stream to the 

-END user terminal and closes the command input file. 

-PAUSE Switches command input stream to the user terminal 

but does not close the command input file. 

-CONTINUE Returns control to command input file following a 

CO -PAUSE or an error. 

-START Resumes command following a BREAK interruption of 

execution of a command file. 

The -TTY, -END and -PAUSE options are used only within command files. 
The -CONTINUE and -START options are typed by the user. 

The -TTY or -END option must be the final command in the command file 
(or in the last command file, if files are chained as described below) . 

A simple command file, C_TEST, might be created to compile the program 
FTN.TEST: 

/*BEGTN TEST OF COMMAND FILE 

CCMOUTPUT OJTEST 

DATE 

/♦COMPILE THE PROGRAM IN 64V MODE 

FTN FTN.TEST -64V 

/*LOAD THE PROGRAM 

SEG 

VLOAD #FTN.TEST 

LO B_FTN.TEST 

LI 

SA 

MAP M_LOADTEST 7 

MAP M_UNSATISFIED 3 

QU 

/♦COMMAND FILE TEST COMPLETED 

DATE 

CCMO -END 

The command file would be executed by the command: 

CO C_TEST 

and would produce the following output file: 
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OK, DATE 

Thursday, October 4, 1979 4:04 PM 

OK, /*COMPILE THE PROGRAM IN 64V MODE 

FTN FTN. TEST -64V 

0000 ERRORS [<.MAIN.>FTN-REV17.1] 

OK, /*LOAD THE PROGRAM 

SEG 

[SEG rev 17.1] 

#VLOAD #FTN.TEST 

$ LO B_FTN.TEST 

$ LI 

LOAD COMPLETE 

$ SA 

$ MAP M_LOADTEST 7 

$ MAP M_UNSATISFIED 3 

$ QU 

OK, /*COMMAND FILE TEST COMPLETED 
DATE 

Thursday , October 4, 1979 4:05 PM 
OK, COMO -END 

Chaining Command Files 

The -CONTINUE option of COMINPUT allows command files to be chained. 
The following example illustrates the chaining of three command files, 
and shows how file unit conflicts can be avoided. The command file 
C_GO contains the following commands: 

/* COMPILE THE PROGRAM IN 64V MODE 

FTN FTN. TEST -64V 

/* LOAD THE PROGRAM 

COMINPUT C_LOADTEST 7 

CLOSE 7 

/* RETURN COMMAND TO USER TERMINAL 

COMINPUT -TTY 

The command file C_LOADTEST contains the following commands: 

/* LOADTEST COMMAND FILE 

SEG 

VLOAD #FTN.TEST 

LO B_FTN.TEST 

LI 

SA 

QU 
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COMINPUT C_MAPS 10 

CLOSE 10 

COMINPUT -CONTINUE 

The command file C_MAPS contains the following commands: 

/* GET FULL MAP AND UNSATISFIED REFERENCES 

SEG 

VLOAD * IFTN.TEST 

MAP M_LCADTEST 7 

MAP MJUNSATISFIED 3 

QU 

/* RETURN TO 'CALLING' COMMAND FILE 

COMINPUT -CONTINUE 7 

Typing COMINPUT C_GO causes PRIMOS to read and execute the commands in 
C_GO. When the command COMINPUT C_LOADTEST 7 is reached, control 
passes to C_LOADTEST, which loads the object file, then calls C_MAPS 
(on file unit '10) to obtain two load maps. When the command COMINPUT 
-CONTINUE is reached in C_MAPS, control returns to the statement 
following the call in C_LOADTEST, which closes the file unit used for 
C_MAP3. When COMINPUT -CONTINUE is reached in C_LOADTEST, control 
similarly returns to C_GO. Finally, the command COMINPUT -TTY in C_GO 
returns control to the user's terminal. 

OK, CO C_GO 

OK, /*COMPILE THE PROGRAM IN 64V MODE 

FTN FTN.TEST -64V 

0000 ERRORS [<.MAIN.>FTO-REV17.1] 

OK, /*LOAD THE PROGRAM 

COMINPUT C_LOADTEST 7 

OK, /*LOADTEST COMMAND FILE 

SEG 

[SEG rev 17.1] 

# VLCAD #FTN.TEST 
$ LO BJFTN.TEST 

$ LI 

LOAD COMPLETE 

$ SA 

$ QU 

OK, COMINPUT C_MAPS 10 

OK, /*GET FULL MAP AND UNSATISFIED REFERENCES 

SEG 

[SEG rev 17.1] 

# VLOAD * IFTN.TEST 
$ MAP M_LOADTEST 7 

$ MAP MJJNSATISFIED 3 
$ QU 

OK, /*RETURN TO 'CALLING' COMMAND FILE 
COMINPUT -CONTINUE 7 
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OK, CLOSE 10 

OK, COMINPUT -CONTINUE 

OK, CLOSE 7 

OK, /*RETURN COMMAND TO USER TERMINAL 

COMINPUT -TTY 

OK, 



Errors 

Non- recoverable errors return input control to the terminal, leaving 
the command file open. The user may type a correct version of the 
offending line, and then resune input from the command file by the 
command CO -CONTINUE. 



Closing Command Input Files ; 

In chaining command files, the 'called' files should be closed upon 
returning to the 'calling' files, either by file unit number (as in the 
example above) or by filename. The user should make certain that the 
file units to be used for the command input files are not already 
opened (or going to be opened) by user programs, utilities, or other 
command input files. 

Note 

The CLOSE ALL command should not be used in a command input 
file, as it closes all files, including the command input file 
from which this command is read. The message 'Unit not open. 
Cominput (Input from terminal.)' will be printed and input 
control will be switched to the terminal. 



THE COMOUTPUT COMMAND 

The COMOUTPUT command writes, into a specified file, both the output 
stream directed to the terminal by PRIMOS and the input presented to 
PRIMOS. The input may originate as direct typing, or come from a 
coirmand file running under COMINPUT, PHANTOM or Batch. The resulting 
output file is a permanent record of the entire dialog. 

Output to the terminal can be suppressed. Print suppression increases 
speed since it normally takes more time to write to a terminal than to 
a disk file. 

The command format is: 

COMOU TPUT [output- file] [-options] 

output- file is the pathname of the file to which the output stream is 
sent, opt ions specify terminal and file output and control flow as 
described below. 
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Terminal Options 

These can be used when the output file is first opened, or at any time 
before the command output file is closed. User input is always echoed 
at the terminal even if the -NTTY option is used. 

-NTTY Turn off terminal output. 

-TTY Turn on terminal output (default) . 

Error messages are printed in the output file and at the terminal, 
regardless of the terminal option selected. Any inter-user terminal 
output (e.g., messages from the supervisor terminal) is printed at the 
terminal but not in the output file. 

File Options 

These stop or restart output to the command file. They may also be 
used to append output to an existing file. 

-PAUSE Stop output to command file; leave file open. 

-CONTINUE Resume output (halted by -PAUSE) to the command output 
file. Or, if at PRIMOS level, re-open an existing 
COMOUTPUT file and position the pointer so that new 
output will be appended. 

-END Stop output to command file; close file. 

A BREAK turns terminal output on, but does not close the file. A 
LOGOUT turns terminal output on and also closes the command output 
file, as well as any other files the user has currently open. For 
example: 

COMO OJFTNTEST 

opens the file 0_FTNTEST for output and positions the pointer to the 
start of the file. If 0_FTNTEST already exists, its previous contents 
will be deleted immediately. To open an existing file for appending, 
type: 

COMO 0_FTNTEST -C 

This opens the file 0_FTNTEST and positions the pointer at the end of 
the file. 
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Closing Command Output Files 

Command output files are closed by the COMO -END command. For example: 

COMO OJTEST 
SLIST RECORDS 
COMO -END 

USING DATE AND TIME IN COMMAND FILES 

The DATE Command 

The command DATE prints the system date and time at the user terminal. 

OK, DATE 
GO 

Wednesday, October 10, 1979 10:11 AM 

OK, 

This feature allows command output files to be stamped with date/time 
information for identification, as an aid to program development and 
debugging. For example, the sequence of commands: 

COMO 0_TEST1 
DATE 



DATE 
COMO -END 

creates a file, 0_TEST1. The first line of this file is the DATE 
command; the next line is the time and date of this interactive 
session. 

DATE may also be included in command input files or in command files 
for Batch execution. 



The TIME Command 

The command TIME entered at the user terminal prints the current values 
in the time accounting registers. These are: connect time, compute 
time, and disk I/O time. 

OK, TIME 

1'32 0'11 0'08 
OK, 
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Connect time is the time since LOGIN (in hours and minutes) . Compute 
time is the time accumulated executing commands or using programs (in 
minutes and seconds) . This does not include disk I/O time. Disk I/O 
time (in minutes and seconds) is the accumulated time for disk input 
and output. Disk I/O includes paging I/O time generated on the user's 
behalf. All times include system supervisor overhead caused by user 
requirements. 

The TIME command can be given before and after executing a program. 
The time differences can be used to benchmark the program and measure 
efficiency as the program is optimized. 

Example : The command input file C_BENCH07 contains the following: 

COMO O_BENCH07 

/* TIMING TEST OF BENCH07 PROGRAM 

DATE 

/* GET START TIME VALUES 

TIME 

SEG #FTN.TEST 

/* GET STOP TIME VALUES 

TIME 

COMO -END 

CO -TTY 

The command CO C_BENCH07 executes this command file. Upon completion, 
the output file O_BENCH07 contains the following: 

OK, /*TIMING TEST OF BENCH07 PROGRAM 
DATE 

Thursday, November 1, 1979 10:24 AM 

OK, /*GET START TIME VALUES 
TIME 

0*11 0'03 0'03 
OK, SEG #FTN.TEST 
The answer is 70 

OK, /* GET STOP TIME VALUES 
TIME 

0'11 0'03 0'04 
COMO -END 



The RDY -LONG Command 

An alternate method of measuring program efficiency is provided by the 
RDY -LONG command. When this command is given, each OK prompt includes 
the time of day, the amount of CPU time (in seconds) and the amount of 
I/O time (also in seconds) used since the last prompt. 
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OK, RDY -LONG 

OK 09:21:29 0.284 0.324 

To return prompts to their normal form, use the command RDY -BRIEF: 

OK 09:21:43 0.036 0.000 

RDY -BRIEF 

OK, 

As an example of using the RDY command, let us modify the command file 
C_BENCH07: 

COMO OJ3ENCH07A 

/*TIMING TEST OF BENCH07 PROGRAM 

DATE 

/*use rdy-long for time between prompts 

RDY -LONG 

SEG #FTN.TEST 

COMO -END 

CO -TTY 

The output file for the new command file is as follows: 

TIMING TEST OF BENCH07 PROGRAM 
DATE 

Wednesday, October 3, 1979 10:06 AM 

OK, /*use rdy-long for time between prompts 

RDY -LONG 

OK 10:06:15 3.560 3.924 

SEG #FTN.TEST 

The answer is 70 

OK 10:06:18 0.287 1.051 
COMO -END 



PHANTOM USERS 

The phantom user feature allows command file processing without tying 
up a terminal. Once a phantom process has been initiated, it is 
treated by PRIMOS as a separate process that is not associated with a 
terminal. The terminal is then made available for other uses. 

The command file run by the phantom process specifies the commands and 
their sequence, program invocations and necessary input data required 
to complete a particular job. Phantoms are used for long compilations, 
loadings, and executions that are debugged and require no interactive 
terminal input. Certain PRIMOS system utilities (e.g., FAM, SPOOL) are 
implemented as phantom processes. 
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Using Phantoms 

A phantom user process is initiated by the command: 

| pathname \ 
PHANTOM (filename) [file-unit] 

filename is the name of a command input file, and file-unit is the 
PRIMOS file unit number on which the command file is to be opened. If 
omitted, file unit 6 is used. 

The PHANTOM command checks for available phantom processes. The number 
varies with each installation. The message: 

No phantoms are available. FILENAME 

is returned if no processes are available. Control is then returned to 
PRIMOS. When a phantom process is available, the message: 

PHANTOM IS USER user-number 

is returned and the phantom user is logged in (under the same 
login-name as the invoker). If the phantom is invoked by the command, 

PH filename 

then the current and home directories of the phantom are the same as 
the current and home directories of the user (or conmand file) invoking 
the phantom. If the phantom is invoked by the command, 

PH pathname 

the phantom's current and home directories are both set equal to the 
invoker' s home directory. User-nunber is the number assigned by PRIMOS 
to the phantom process. Control returns to PRIMOS, the terminal is 
freed for other use, and the phantom command file is opened on the 
specified (or default) unit. PRIMOS then reads all further commands 
for the phantom user from the command file. 



Phantom Operation 

Phantom processes should not execute programs which require input from 
an actual terminal. Such an instruction will abort and log out the 
phantom process. This logout information is printed only at the 
supervisor terminal. 

While a phantom process is in operation, terminal output is suppressed 
unless a command output file has been opened by a COMOUTPUT command in 
the phantom command file. Output is then written to the COMOUTPUT 
file. 
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It is possible to initiate another phantom from a running phantom, in a 
manner similar to chained COMINPUT files. However, there is no 
guarantee that a phantom user process will be available when the 
process is requested by a command file. 

The final command in the last executed phantom command file should be 
LOGOUT. 



Phantom Logout 

At the completion of a job process, phantom users are automatically 
logged out. To cancel a phantom user process before completion, use 
the command: 

LOGOUT -user-number 

user- number is the PRlMOS-assigned phantom user number. 

Any phantom can be logged out from the supervisor terminal . From a 
user terminal, a phantom can be logged out only if the terminal has the 
same login UFD as that which initiated the phantom. 

Phantom STATUS Information 

The STATUS USER command (discussed in Section 3) , provides a list of 
all the users in the system, their login numbers, assigned line 
numbers, etc. Phantom users are distinguished by the line number 77 in 
a STATUS list. In the following example, the phantom users are numbers 
57 through 61, as indicated by LIN = 77. 



OK, status users 


USER 


NO 


LIN 


PDEVS 


SYSTEM 


1 


76 


3462 SMLC00 SMLC01 


GOG 


7 


5 


71063 


HEISIN 


14 


14 


460 (END ) 


MANN 


18 


20 


71063 


SCHWAR 


19 


21 


(TO END ) 


YLEE 


27 


31 


3462 


STUMPF 


30 


34 


3462 


FEHSKE 


37 


43 


3462 71063 


GMS 


38 


44 


3462 


MAM 


39 


45 


3462 


J.COOK 


45 


53 


(TO END ) 


STEF 


46 


54 


71063 


BS 


49 


75 


460 (END ) (FROM END ) 


WMM.B 


50 


75 


71063 460 (ENE ) (FROM END 


WEBB 


51 


75 


3462 (FROM END ) 


DEBBY 


52 


75 


71063 (FROM END ) 


DPF.B 


53 


75 


460 (END ) (FROM ENE ) 


TEKMAN 


54 


75 


71063 (FROM BDSF ) 
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FAM 57 77 3462 (2) 

SYSTEM 58 77 460 (3) 

SYSTEM 59 77 460 PR0 

SYSTEM 60 77 460 PR1 

QMS 61 77 3462 

OK, 



Example of Phantom Command File 

The phantom command file PH_TEST contains the following commands: 

/*BEGIN TEST OF PHANTOM 

COMOUTPUT 0_PH_TEST 

DATE 

/♦COMPILE THE PROGRAM IN 64V MODE 

FTN FTN.TEST -64V 

/*LOAD THE PROGRAM 

SEG 

VLOAD #FTN.TEST 

LO B_FTN.TEST 

LI 

SA 

MAP M_LOADTEST 7 

MAP MJJNSATISFIED 3 

QU 

/*PHANTOM TEST COMPLETED 

DATE 

/*CQMO -E would normally go here. 

/* It has been omitted so the logout sequence 

/* could be shown in the comoutput file. 

LOGOUT 

When a phantom is invoked at the terminal by PH PH_TEST, the terminal 
interactive dialog is: 

OK, PH PH JEST 
PHANTOM IS USER 61 
OK, 

The contents of the command file, 0_PH_TEST, created by the phantom 
are: 

OK, DATE 

Friday, October 5, 1979 10:06 AM 

OK, /"COMPILE THE PROGRAM IN 64V MODE 

FTN FTN.TEST -64V 

0000 ERRORS [<.MAIN.>FTN-REV17.1] 

OK, /*LOAD THE PROGRAM 

8 - 13 January 1980 



SECTION 8 IDR4130 



SBG 

[SEG rev 17.1] 

# VLOAD #FTN.TEST 

$ LO B_FTN.TEST 

$ LI 

LOAD COMPLETE 

$ SA 

$ MAP M_LOADTEST 7 

$ MAP MJJNSATISFIED 3 

$ QU 

OK, /*PHANTOM TEST COMPLETED 
DATE 

Friday, October 5, 1979 10:06 AM 

OK f /*CQMO -E would normally go here. 

/* It has been omitted so the logout sequence 

/* could be shown in the comoutput file. 

LOGOUT 

TEKMAN (62) LOGGED OUT AT 10 '06 100579 

TIME USED= 0'00 0'01 0'02 
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SECTION 9 
BATCH JOB PROCESSING 



INTRODUCTION 

Batch is the most flexible of the PRIMOS command file utilities. Any 
command file that will run under FRIMOS can be run as a Batch job. 
This means that users may write command files for submission as Batch 
jobs without including special Batch commands. Yet users may also run 
existing COMINPUT, PHANTOM, and CX files as Batch jobs; Batch will 
accept them all. 

Batch offers further flexibility in job scheduling and execution 
control. Each Batch queue has a phantom from which to run users' jobs. 
These phantoms run "in the background" of the system: that is, they 
run concurrently with interactive jobs, but at somewhat lower 
priorities. Thus, they use only small amounts of CPU time when 
interactive use is heavy, but utilize large amounts of CPU time when 
interactive use is light or absent. Furthermore, Batch jobs may be 
held in their queues by operators, then released to run at appropriate 
times. Thus, extremely long jobs, such as file updates and backups, 
can be set up as Batch jobs during the day, then run under operator 
control at night. 

Each Batch queue is a separate entity, defined by the System 
Administrator to be particularly hospitable to certain types of jobs. 
Queues designed for short jobs have a fairly high scheduler priority, 
but a short timeslice; queues designed for normal jobs have slightly 
lower priorities and normal timeslices. Queues designed for long jobs 
have low priorities but large timeslices. The queues for short jobs 
will thus run fastest, as they can operate during times of heavier 
interactive use. The other queues will take fuller advantage of 
periods of lighter activity. By using the BATGEN (BATch GENeration) 
command, explained below, users can see what queues are available and 
what their characteristics are. They can then submit their jobs to the 
appropriate queues. 



USING THE BATCH SUBSYSTEM 

Users communicate with the Batch subsystem through four commands: 
BATCH, BATGEN, JOB, and $$ JOB. With these commands, they can: 

• Submit jobs (JOB) 

• Set job parameters (JOB, $$ JOB) 

• Modify, cancel, abort, or restart jobs (JOB) 
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• Monitor sub system usage (BATCH) 

• Monitor queue characteristics and availability (BATGEN) 
These operations are described below. 

SUBMITTING BATCH JOBS 

To submit a job, use the command: 

-ACCT information 



JOB pathname-1 



I seconds 



-CPTIME 



• 



-ETIME ■ 



[NONE 
minutes 
NONE 
-FUNIT nunber 
-HOME pathname-2 
-PRIORITY value 
-QUEUE queue-name 

(yes 

-RESTART* 

l N0 ) 



J 



Batch will then send a "job submitted" response announcing the job's 
job- id number and reminding the user (if he didn't use the -HOME 
option) of the home UFD for the job. For example: 

OK, job pnjob 
[JOB rev 17.2] 

Your job, #00015, was submitted to queue Normal-1. 
Home=<MISCEL>TEKMAN>ALICE>ALICE2 

As this example shows, jobs may be submitted without options. The 
Batch monitor places these jobs in the first available queue and uses 
that queue's default values for all necessary parameters. On the other 
hand, users may specify queue and/or parameters, using the JOB 
command's options as described below. 

Note 

All numbers must be decimal integers. 
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Option 
-ACCT information 



-CPTIME 



seconds 
NONE 



-ETIME 



minutes 
NONE 



-FUNIT nunber 



-HOME pathname 



Description 

Allows the user to specify accounting 
information for his job. The information 
must be 80 characters or less in length. It 
may not be an explicit register setting 
(octal nunber) or be preceded by an unquoted 
minus sign. If the information contains 
spaces, commas, or comment delimiters (/*) it 
should be enclosed in apostrophes. (Ebr 

example: -ACCT 'OK, HERE WE GO') . The 
in f o rmat i on will be included in job DIS PIAYs , 
but will not be used in running the job. 

Specifies the maximum amount of CPU time (in 
seconds) to be allotted to the job. NONE 
requests that no time limit be placed on the 
job. If the job exceeds the time limit, it 
will be aborted. 

Specifies (in minutes) the elapsed time to be 
allowed before the job is aborted. Details 
are the same as those for -CFTIME. 

Specifies the file unit to be used for 
command input. Permissible values range from 
1 to 16, to 1 to 126, depending on the limit 
set by the System Administrator. Default 
depends on the queue to which the job is 
submitted. It is usually 6. 

Specifies the UFD in which a job is to run. 
Using this option has the same effect as 
providing an ATTACH command as the first line 
of the command file. The pathname for a 
-HOME option, however, may not be a null 
specification or a relative pathname (i.e., 
it may not begin with *» , and may not exceed 
80 characters in length. 



-PRIORITY value 



Determines the job's priority within its 
queue. Possible values are from to 9, with 
9 being the highest (most favored) priority. 
The default depends on the queue. 



-QUEUE queuename 



-RESTART 




Names the queue in which the 
placed. (To learn the 
characteristics of queues, 
-DISPLAY command.) 



job should be 

names and 

use the BATGEN 



Determines whether a job can be restarted 
following an ABORT or a system shutdown. The 
default is always YES. 
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If, for any reason, the Batch monitor cannot accept the job as 
submitted, it will send the user error messages containing the 
information he needs to resubmit the job successfully. These messages 
are listed in Appendix A; they are generally self-explanatory. 



SUPPLYING OPTIONS VIA THE $$ JOB COMMAND 

Any or all of the JOB command* s eight options may be given in the first 
non-comment line of the command file itself by the command: 

$$ JOB username {options} 

Users will probably find this command handiest for parameters they 
expect to remain constant whenever the job is submitted, and the JOB 
command options handiest for parameters which change from submission to 
submission. 

Parameters given in the $$ JOB command line may be overridden by giving 
a different value for the same parameter in the JOB command. For 
instance, if you specified "$$ JOB RESEARCH -CPTIME NONE" in your file, 
but wanted to run the job in a queue which had a CPU time limit, the 
command "JOB TEST_SCORES -CPTIME 180 -QUEUE FAST" would run the job in 
queue FAST with a CPU time limit of 180 seconds. 

Note 

With one exception, any Batch command file, even one including 
a $$ JOB command, can be run as a command input file. The 
exception is a file using the $$ JOB -HOME option. When run as 
a command input file, the $$ JOB line will be ignored, and no 
ATTACH will be done. In this case, add an ATTACH command to 
the file immediately following the $$ JOB line. 



CONTROLLING BATCH JOBS 

Modifying Parameters 

To modify a job 1 s parameters after it has been submitted, use the 
-CHANGE option of the JOB conmand: 

r n 

-ACCT information 

-CPTIME | seconds 

(none 

-ETIME Jminutes 

\NONE 
-FUNIT number 
-HOME pathname 
-RESTART lYESl 
V \N0 J 



[jobname\ 
JOB { job- id j -CHANGE < 
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For example: 

JOB #10039 -CHANGE -ACCT 'research' -HOME ECON>STATISTICS 
JOB TEST-SCORES -CHANGE -FUNIT 8 -RESTART YES 

A job's -QUEUE and -PRIORITY options cannot be CHANGEd. If they are in 
error, the job must be CANCELed and resubmitted. 



Restarting Jobs 

Users wishing to CHANGE jobs which are already running can do so by 
following a JOB -CHANGE command with a JOB -RESTART command. For 
example: 

JOB TEST-SCORES -CHANGE -HOME RESEARCH>STATS>NEWSTATS 
JOB TEST-SCORES -RESTART 

This procedure will mark the changes in the job's status, terminate 
execution, and then flag the job as ready for restarting under its new 
conditions. 

Note 

Distinguish between the -RESTART YES/NO option and the -RESTART 
command. The option always takes an argument; it signals 
whether or not a job may be restarted. The -RESTART command 
takes no argument; it attempts to abort and restart the job. 

Canceling Jobs 

To prevent a waiting or held job from running, use the command: 
f jobnamel 

.TOR I i oh- id l-CANrFT. 

This command will not halt a job that is already running; but it will 
mark that job as unrestartable . 



Aborting Jobs 

To terminate execution of a job already running, use: 

{jobnamel 
job- id j -ABORT 

This command cancels a waiting or held job and forces a running job to 
log itself out immediately. 

The JOB -CHANGE, -CANCEL, -ABORT, and -RESTART commands will accept a 
filename in place of a job- id only if that filename is unique among the 
user's active jobs. Thus, if file C_TEST has been submitted once, the 

9-5 January 1980 



SECTION 9 



IER4130 



command "JOB CJTEST -CANCEL" will work. But if two submissions of 
C_TEST (for example, #10057 and J10064) are active, you must use the 
job- id to tell the monitor which job to cancel. The monitor accepts 
only one command at a time; JOB CJTEST -ABORT -RESTART is illegal, as 
is JCB #10035, #10039 -CANCEL. 



MONITORING BATCH 

Users may monitor their own jobs within the Batch system by using the 
JCB -STATUS and JCB -DISPLAY commands; they may monitor subsystem 
usage through the BATCH HDISPLAY command; and they may monitor the 
characterisitics and availability of queues through the BATGEN -DISPLAY 
and BATGEN -STATUS commands. These commands work as follows: 



B 



job- id "I (-STATUS | 



JOB [jobnamej j-DI SPLAY j 



Monitors the progress of the user's own jobs. The -STATUS and DISPLAY 
options govern the amount of information to be shown, while the jobname 
and job-id options allow the user to specify the jobs on which he wants 
information, as follows: 



Option 
job- id 



jobname 



Description 

A 5-digit number assigned to a job by the 
monitor when the job is placed in a queue. 
Use the job-id to request information on one 
job only. 

The name of the file being run. If the job 
was submitted as a pathname (e.g., JOB 
FELLCWSHIP>H0BBITS>FRODO) , its jobname is the 
final element of the pathname (e.g., FRODO) . 
Use this format to request information on 
multiple submissions of a file. 



(Omitting jobname and job- id requests information on all 
active jobs.) 



the user's 



-STATUS 



-DISPLAY 



Prints out the job's jobname and job- id, the 
name of the queue in which it is placed, and 
its execution status: whether it is held, 
waiting, running, completed, or aborted. 

Provides status information and values for 
all JOB and $$ JOB command options (except 
for "HOME") — both those specified by the 
user and those assumed from queue-defined 
defaults. 
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P» BATCH -DISPLAY 

Monitors Subsystem Usage. It prints the number of jobs waiting in each 
queue and lists all jobs currently executing, identifying them by user 
job- id, phantom user-number, and queue. For example: 

OK, batch -display 
[BATCH rev 17.2] 

Number of waiting and held jobs: 

Queue Jobs 



Normal-2 76 

Currently running jobs: 

User Jobid# # Queue 



TURNER #10032 60 Normal-2 
BURLEY #00172 62 Normal-1 



^ BATGEN -STATUS 



Lists the currently defined queues and notes whether each is blocked 
(not accepting jobs) or unblocked (available for use) . 



)► BATGEN -DISPLAY [queuename] 

Identifies and gives full characteristics for each queue, if queuename 
is not specified. If queuename is specified, gives characteristics for 
that queue only. For example: 

OK, batgen -display normal 
[BATGEN rev 17.2] 

Queue name = normal, unblocked. 
Default cptime=30, etime=None, priority=5; 
Maximum cptime=180, etime=NOne; Funit=6; 
Delta rlevel=l; Timeslice=20; 

In this example, normal is the queue's name. Unblocked means that the 
queue is accepting jobs for queueing and execution. The default cptime 
and etime values will apply to jobs that don't specify their own CPU 
time or elapsed time options. The maximum cptime and etime values are 
the largest allowed for any job running from the queue. Priority and 
funit are default values for those options. 
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Delta rlevel and timeslice refer to run-time priorities. Queues with 
high delta rlevels and large timeslices are best for long jobs; queues 
with low delta rlevels and short timeslices are best for short jobs. 
The queue in the example is designed for average jobs. 



Note 

If the System Administrator has not read-enabled the BATDEF 
file, the BATGEN commands will return error messages. In this 
case, users needing information about queues should see their 
supervisor, the operator, or the System Administrator. 
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FILE-HANDLING UTILITIES 

INTRODUCTION 

This section introduces you to Prime's basic file handling utilities. 
These utilities allow you to: 

• Sort one or more unsorted files into one sorted file (SORT) 

• Merge several sorted files into one sorted file (SORT) 

• Compare files with each other (CMPF) 

• Resolve differences between files (MRGF) 

• Move files and subdirectories between directories (FUTIL) 

• Copy or delete entire directories (FUTIL) 

SORTING FILES (SORT) 

The SORT command sorts up to 20 files, on up to 50 keys, into a single 
output file. SORT preserves the order of input for records with equal 
keys (i.e., it is a stable sort) . 

Most sorts are done on ASCII files (also called compressed files) , such 
as those created by the text editor (ED) . The following discussion 
emphasizes how to do ASCII sorts. In addition, SORT can process 
uncompressed files, variable length files (also called binary files) , 
and fixed length files. The basic format for using SORT is the same 
for every file type, but details vary from type to type. The PRIMOS 
Commands Reference Guide contains complete information and sorting 
instructions for each file type. 

Using SORT 

To use SORT, provide information in a three- or four-step sequence, as 
follows: 

1. Give the SORT command. 

2. Specify the sort files and nunber of sort fields, either by a 
simple parameter list or by the use of keywords. 

3. Specify the starting and ending columns of sort fields (keys) . 

4. If -MERGE is specified, enter additional filenames. 
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SORT normally specifies the information it wants at steps 2, 3, and 4. 
However, once you are familiar with the prompt dialog, you can suppress 
the printout by using the -BRIEF option with the command line. If 
-BRIEF is specified, simply give the information line by line in the 
same order SORT asks for it. Refer to the sample sort that concludes 
this discussion for an example of the SORT dialog. 



The SORT Command 

To invoke SORT, give the sort command, either by itself or accompanied 
by one to three options: 

SORT [-BRIEF] [-SPACE] [-MERGE] 

The meaning of the options is as follows: 

Option Meaning 

-BR IEF SORT does not print requests for information. 

-SPA CE Any blank lines are deleted from the SORT output file. 

-MER GE A mergesort (a merge of 2 to 11 presorted files) is 
requested. A mergesort is faster than a straight 
sort, but it cannot handle unsorted files. 

SORT responds by requesting: 

• The name of the file to be sorted 

• The name of the output file to be created 

• The number of keys for the sort (default is 1) 

Simple File and Key Specifications 

The simplest type of sort reads one unsorted ASCII file and creates 
another sorted ASCII file. To specify this sort, simply list the 
filenames and number of keys (if greater than 1) on one line, then list 
the starting and ending columns for each key field on a separate line. 
If the data within a key field are to be sorted by some code other than 
straight ASCII, type a space and the data type after the ending column. 
(The SORT dialog will list data types and their codes. They are also 
explained, in greater detail, in the PRIMOS Commands Reference Guide.) 
If the sort on any key is to be done in reverse (descending) order, 
type a space and an "R" after the ending column or data type. For 
example, to sort a list of names and addresses, the entire entry of 80 
characters might constitute the sort field, and the commands would run: 
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OK, SORT -BR 

JUMBLED. N^MES NEAT. NAMES 

1 80 



Unless the -MERGE option has been specified, sorting begins when the 
last pair of column numbers is entered. When the sort is complete, 
SORT prints at the terminal the number of passes needed for the sort 
and the number of items (i.e., lines) placed in the output file, and 
then returns to PRIMOS. 



Other File Specifications 

If you are sorting more than one file, give all filenames plus the 
number of keys on a single line in the following format: 

-INPUT inputfile [...-INPUT inputfile] -OUTPUT output file -KEYS n 

For example: 

OK, sort -brief 

-input chaos. 1 -input chaos. 2 -output order -keys 2 

1 10 

15 20 r 

BEGINNING SORT 



PASSES 2 ITEMS 10 

[SORT-REV17.0] 

OK, 

If you are sorting uncompressed or fixed length files, or if you are 
sorting binary files using ASCII keys, you will have to specify 
additional file information (via keywords) along with the filenames. 
See the PRIMOS Commands Reference Guide for details. 



Key Specifications 

SORT recognizes 12 types of keys. ASCII files (compressed and 
uncompressed) can use seven of them: A and AU for alphanumeric data, 
U, LS, TS, LE and TE for numeric data. 



Alphanumeric keys : The two alphanumeric keys are ASCII (A) , which 
sorts in a strict ASCII sequence, and ASCII, upper and lower (AU), 
which sorts all alphanumeric characters as if they were upper case. 
(The ASCII sequence is given in Appendix C.) 



10-3 January 1980 



SECTION 10 IDR4130 



The default key type is strict ASCII (A) . This represents a departure 
from the Rev. 16 ASCII default, which sorted lower Case equal to 
upper, as AU does now. Given the four words, APPLE, alphabet, WHY, and 
whynot, ASCII (A) produces: 

APPLE 
WHY 

alphabet 
whynot 

AU produces: 

alphabet 
APPLE 
WHY 
whynot 



Numeric keys : Three common numeric keys for ASCII sorts are: 

U nunbers without plus or minus signs 

LS numbers preceded by plus or minus signs 
(Numbers without signs are considered positive.) 

TS numbers followed by plus or minus signs 

(Numbers without signs are considered positive.) 

(The LE and TE keys, which have the sign embedded in the numeral, are 
explained in the PRIMOS Commands Reference Guide.) 

Here is an example of a sort on an LS key: 

OK, sort -br 
numbers numbers. 1 
1 10 Is 

BEGINNING SORT 



PASSES 2 ITEMS 

[SORT-REV17.0] 
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OK, slist numbers. 1 

-9999 

-8205 

-6783 

4114 
+5483 

8265 
+9765 

OK, 



Additional Filenames for MERGE Operation 

After key fields have been specified using the -MERGE option, SORT asks 
for the number of additional files to be merged, if you have already 
listed all input files with the -INPUT format, this number is 0. 
Otherwise, give the number of additional files and then the names of 
the files, one name per line. When the last name is entered the 
mergesort begins. When the merge is complete, SORT prints the number 
of passes and returns to FRIMOS. 

Note 

In previous versions of PRIMOS (Rev. 16 and earlier) 
SORT-MERGE would sort and then merge unsorted files. The 
sort-and-merge process has now been taken over by SORT itself, 
freeing SORT -MERGE to do a true mergesort: i.e., a merge of 
presorted files. 

A Mergesort Example 

Here is an example of a mergesort. Assume we have created two 
transaction files, in which each line (record) has the following 
format: a transaction number in columns 1-5, a credit or debit 
notation in column 6, a customer name in columns 8-17, a customer ID 
number in columns 19-25, and other data in the remaining columns. Each 
file has been sorted by customer name, customer ID, and transaction 
number (in reverse order, so that most recent transactions come first) . 
Now we are going to merge the two files, sorting on the same three 
keys. The sort, with the full SORT dialog, is as follows: 
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OK, sort -merge 

SORT PROGRAM PARAMETERS ARE: 

INPUT TREE NAME — OUTPUT TREE NAME FOLLOWED BY 
NUMBER OF PAIRS OF STARTING AND ENDING COLUMNS, 
cust. credits cust.accts 3 

INPUT PAIRS OF STARTING AND ENDING COLUMNS 
ONE PAIR PER LINE— SEPARATED BY A SPACE. 
FCR REVERSE SORTING ENTER "R" AFTER DESIRED 
ENDING COLUMN—SEPARATED BY A SPACE. 
FOR A SPECIFIC DATA TYPE ENTER THE PROPER CODE 
AT THE END OF THE LINE— SEPARATED BY A SPACE. 
"A" - ASCII 

PRECISION INTEGER 
PRECISION REAL 
PRECISION REAL 
PRECISION INTEGER 

- NUMERIC ASCI I, UNSIGNED 

- NUMERIC ASCII, LEADING SEPARATE SIGN 
"TS" - NUMERIC ASCI I, TRAILING SEPARATE SIGN 
"LE" - NUMERIC ASCII, LEADING EMBEDDED SIGN 
"TE" - NUMERIC ASCII, TRAILING EMBEDDED SIGN 
"PD" - PACKED DECIMAL 

"AU" - ASCII, UPPER LOWER CASE SORT EQUAL 

DEFAULT IS ASCII. 
8 17 
19 25 
1 5 r 
INPUT THE NUMBER OF ADDITIONAL FILES TO BE MERGED. 

INPUT FILES TO BE MERGED, ONLY ONE PER LINE, 
cust.debits 



II -rll 
II nit 

"D" 
ii j ii 

"U" 
"LS" 



- SINGLE 

- SINGLE 
-DOUBLE 

- DOUBLE 



(MAX= 



10) 



BEGINNING MERGE 



PASSES 



ITEMS 



10 



[SORT-RE V17. 2] 



OK, slist cust.accts 






89424+ Jones 


BR9438 


other data about 


transaction 


81884- Jones 


BR9438 


other data about 


transaction 


12345+ Jones 


BR9438 


other data about 


transaction 


67340- Jones 


XL1489 


other data about 


transaction 


54936+ Jones 


XL1489 


other data about 


transaction 


49480- Jones 


XL1489 


other data about 


transaction 


86889+ Smith 


CS4192 


other data about 


transaction 


29622+ Snith 


CS4192 


other data about 


transaction 


23220- Smith 


CS4192 


other data about 


transaction 


21220+ Smith 


CS4192 


other data about 


transaction 



OK, 
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FILE COMPARISON (CMPF) 

The PRIM06 command CMPF permits the simultaneous comparison of up to 
five ASCII files of varying lengths. The format is: 

CMPF file-1 file-2 [ file-5] [options] 

The first file, file-1 , is treated as the original file against which 
the other files are compared. The CMPF command produces output 
indicating which lines have been added, changed or deleted in the other 
files. 

The options which may be specified are: 

Option Function 

-BRIEF Suppresses the printing of differing lines 

of text of files being compared. Only 
identification letters and line numbers are 
printed. 

-MINL number Sets the minimum nunber of lines that must 

match after a discrepancy between files is 
found. Needed in order to resynchroni ze 
file comparison. Default = 3 lines. 

-REPORT filename Produces a file with specified filename, 

containing the differences found between 
compared files (in lieu of displaying them 
at the terminal during the comparison 
process) . 

After a difference between the original file and another specified file 
has been discovered, CMPF attempts to resynchroni ze the files for 
comparison. This occurs only when a certain number of lines match in 
all the files being compared. The default value is 3, but can be 
changed in the -MINL option. The comparison process continues until 
another difference is found. 

fohen line differences are reported, either at the terminal or in a 
report file, each line from the original file is indicated by the 
letter A, followed by the line number of the line containing 
discrepancies. The corresponding lines of other files are indicated in 
the same manner using letters B through E respectively. 
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Example : Consider the following two files: 

FILEA FILEB 



The 


The 


quick 


swift 


brown 


red 


fox 


fox 


jumps 


junps 


over 


over 


the 


the 


lazy 


dog 


dog 





A CMPF comparison of these two files works as follows: 

OK, CMPF FILEA FILEB 
GO 

A2 quick 

A3 brown 

CHANGED TO 
B2 swift 

B3 red 



A8 lazy 

DELETED BEFORE 
B8 dog. 

COMPARISON FINISHED. 
2 DISCREPANCIES FOUND. 



OK, 

MERGING TEXT FILES (MRGF) 

The MRGF command merges up to five ASCII files. The format is: 

MRGF file-1 [file-2 ...file-5] -OUTF outf ile [options] 

The first file specified is treated as the original file, and it is 
assumed that changes have been made to this file to produce the other 
files. Pathnames may be used to specify files to be merged. Unchanged 
lines of text and noncon flic ting changes between files are 
automatically copied to the output file, outfile . When corresponding 
lines of text in the files differ, the user is asked by the MRGF 
program to solve the conflicts. This is done by entering an 
interactive mode in which the user can specify the contents of the 
output file. In this mode, the command x (x = A-E) causes all the 
queried lines from file X to be inserted; the command xn causes line n 
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from file X to be inserted. New text can be inserted by entering a 
blank line at the terminal (thus sending MRGF into input mode) , typing 
the new text, and then typing another blank line. No text editing can 
be performed on lines thus input, and no expansion of tab characters 
will be done. The lines must be entered character-for-character as 
they are to appear. 

The options taken by the MRGF command are similar to those for the CMPF 
command. There is an additional option, -FORCE, which causes file-2 to 
be the preferred file if conflicts exist between several files. No 
MRGF interactive dialog will be generated when conflicts arise if the 
-FORCE option is used. File-2 is assumed 'correct' and the other files 
forced to comply with it. 



FILE UTILITY (FUTIL) 

FUTIL is a file utility command for copying, deleting, and listing 
files and directories. FUTIL is most often used for copying files and 
directories from one directory to another. It is also useful for 
deleting groups of files and entire directories. Its list option 
allows the user to examine file and directory properties and to keep 
track of the contents of directories involved in the copy or delete 
processes. FUTIL allows operations on files within User File 
Directories (UFDs) and segment directories. 



Invoking FUTIL 

To invoke FUTIL, type FUTIL. When ready, FUTIL prints the prompt 
character >, and waits for a command string from the user terminal. 
FUTIL accepts either upper- or lower-case input, but passwords must be 
entered exactly as they have been created. (Most other commands will 
convert passwords to upper case before attempting the match. FUTIL 
does not.) To abort long operations (such as LISTF) , type BREAK, and 
restart FUTIL by typing S 1000. 

To use FUTIL, type one of the FUTIL subcommands (listed below) followed 
by a carriage return, and wait for the prompt character before issuing 
the next command. The erase (") and kill (?) characters are supported 
in both command and subcommand lines. 



FUTIL Commands 

Although only the major FUTIL commands are discussed in detail here, 
the following figures illustrate the function of all available FUTIL 
comands. Figure 10-1 is an overview of all FUTIL commands. Figure 
10-2 outlines the COPY, DELETE and EROTEC commands and how they operate 
on files and directories. A typical FROM and TO directory outline is 
included to show how commands move files and directories from one 
location to another. 
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Below are some examples of the most commonly used FUTIL commands. An 
overview of FUTIL commands appears at the end of this section. For 
complete details on all the FUTIL commands, which are summarized at the 
end of this section, see Reference Guide, PRIMOS Commands. 



Copying Files and Directories 

FUTIL provides several commands which allow the user to copy files, 
directories, or directory trees. These commands, their functions and 
formats are listed below: 

Command Function 

COPY Copies files (as many as will fit on line) . 

TRBCPY Copies directory trees. 

UFDCPY Copies entire UFD structure (complete with all 
files) . 

TO Specifies directory to which file(s) or directories 

are to be copied. Accepts a pathname. Default is 
home directory. 

FROM Specifies directory from which files or directories 

are to be copied. Accepts a pathname. Default is 
home directory. 

The general formats of these comands are: 

COPY filename [new-name] , [filename new-name] 

TRBCPY filename 

UFDCPY 



Copying Files : In order to copy a file, the user must have read 
access rights. The name of a file may be changed by indicating the 
desired new name immediately after the current name has been 
specified. Filename pairs are separated by commas on the command 
line. 

The tree structure in Figure 10-3 illustrates the positions of 
various files and directories which can be copied from one point to 
another, as shown in the following hypothetical situations. 

Situation 1 : Suppose we want to copy the files HITS and MISSES 
from the directory NAUTILUS, into our current directory, SECRETS. 
We are currently attached to SECRETS and have also set it as home. 
The pathname of SECRETS is represented as follows: <*>SECRETS. 
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In pathnames, <*> represents the current disk. In this case, it 
represents disk 2. This pathname can also be represented as 
<MONITCR>SECRETS. MONITOR is the volune-name of the logical 
device, v*iereas 2 is the volume-number. Similarly, in Figure 10-3, 
the volune-name and number of the other logical disk are NAVY and 1 
respectively. The volune-name and number can be used 
interchangeably in a pathname, and both appear in the following 
examples. Any directory subordinate to SECRETS would be described 
by a relative pathname, as in, *>DOMESTIC. In relative pathnames, 
the use of * indicates the home directory. 

To move files from any directory to the current directory, the 
following general steps are taken: 

1. Invoke FUTIL. 

2. Define the FROM directory. 

3. Define the files to be copied and indicate new filenames 
(optional) . 

The FUTIL dialog for this particular situation is: 

OK, FUTIL 

[FUTIL rev 17.0] 

>FROM <1>MARINE>NAUTILU5 

> COPY HITS, MISSES ZEROES 

>QUIT 

OK, 

The files HITS and ZEROES (formerly MISSES) are now in our home 
directory SECRETS, as well as in the FROM directory NAUTILUS. 
Notice that a TO directory was not specified. If the TO directory 
is not explicitly indicated, FUTIL assumes it to be the current 
directory. Although the file MISSES is called ZEROES in the 
current directory, its name is not changed in the original, or 
FROM, directory. 

Situation 2 : Suppose we want to copy all the contents of the 
directory HOLLAND to another directory CLASSIFIED, on the current 
disk. The files and directories contained in HOLLAND are called a 
directory tree. The FUTIL dialog would be as follows: 

OK, FUTIL 
[FUTIL rev 17.0] 
> FROM <1>MARINE 
>T0 <*>CLASSIFIED 
>TRECPY HOLLAND 

>2 

This copies the directory HOLLAND (with its subordinate files and 
directories) to the directory CLASSIFIED. The <*> indicates the 
current disk. HOLLAND is now a subdirectory in CLASSIFIED. 
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Situation 3 : Suppose we wish to copy the entire directory tree 
MARINE into the UFD REPORTS. The FUTIL dialog would be: 

OK, FUTIL 
[FUTIL rev 17.0] 
>FROM <NAVY>MARINE 
> T0 <MCNITOR>REPORTS 
>UFDCPY 

>Q 

The entire batch of files and directories listed under the UFD 
MARINE are now listed as a subdirectory under the UFD REPORTS. 

Situation 4 : We can also copy files from our home (current) 
directory to another. It is not necessary to specify a FROM name. 
In the absence of a FROM specification, FUTIL assunes the FROM 
directory to be the current working directory. Simply specify the 
directory to which the files are to be copied. 

The current directory in this situation is NAUTILUS. FUTIL allows 
you to move to other directories with the ATTACH subcommand, 
abbreviated "A". It is not necessary to return to PRIMOS in order 
to change the working directory location. For example: 

OK, FUTIL 

[FUTIL rev 17.0] 

> A <1 >MARINE>NAUTILUS 

The directory NAUTILUS is now the current working directory. To 
copy the file HITS from the current directory up to the directory 
MARINE, do the following: 

> T <1>MARINE 
> C HITS 
>Q 



Deleting Files and Directories 

Commands for deleting files, directory trees and UFDs are: 

Cortmand Function 

DELETE Deletes specified files from FROM directory. 

TREDEL Deletes specified directory trees or segment 
directories, including MIDAS files, from FROM 
directory. 

UFDDEL Deletes entire specified UFD. 
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The user must have read, write, delete/ truncate access rights to 
delete any file. Below are some situations in which FUTIL is used 
to delete several types of files and directories. 

Situation I t In order to delete the file HITS from the sub-UFD 
NAUTILUS, the following dialog could be used: 

OK, FUTIL 
[FUTIL rev 17.0] 
>FRQM <NAVY>MARINE>NAUriLU3 
>DELETE HITS 

>Q 

Situation 2 : If we wanted to delete the directory tree rooted in 
the sub-UFD HOLLAND, we would do the following : 

OK, FUTIL 
[FUTIL rev 17.0] 
>FROM <1>MARINE 
>TREDEL HOLLAND 

OK, 

This deletes the directory HOLLAND and its entry in MARINE. 
Similarly, to delete segment directories and MIDAS files, use the 
TREDEL option, as shown. 

Situation 3 : To delete the contents of CLASSIFIED appearing on 
the current disk, (2), the following dialog could be implemented: 

OK,FUTIL 
[FUTIL rev 17.0] 
>FROM <*>CLASSIFIED 
>UFDDEL 
>QUIT 
OK, 

This deletes all subordinate directories and files from the UFD 
CLASSIFIED. The directory itself, however, is not deleted. 



Listing Contents of a Directory 

The LISTF command in FUTIL displays a list of all the files and 
directories in the FROM directory. It also displays the FROM 
directory pathname and the TO directory pathname (default) . The 
various options to the LISTF cortmand provide information on all the 
files contained in the FROM directory. 
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FUTIL COMMAND SUMMARY 
ATTACH pathname 

Changes working directory to pathname . 



CLEAN prefix [level] 

Deletes files beginning with prefix , for indicated nunber of 
levels (default=l) . 



COPY from-name [to-name] [,from-name [to-namel] ... 

Copies named files from FROM directory to TO directory. If 
to-name s are omitted, copies have same names as originals. 



COPY (from-position) [ (to-position)] 

Copies from one segment directory to another. If to-position 
is omitted, copy goes to same position as original. Note that 
COPY from-name (to-position) and COPY (from-position) to-name 
are also legal. 



COPYDA M 

Same as COPY but sets file type of copy to DAM. 

COPYSA M 

Same as COPY but sets file type of copy to SAM. 

CREATE directory [owner-password [non-owner-password] ] 

Creates directory in current TO directory (with optional 
passwords) . 



DELETE 



jfile-a [file-b] ... \ 

\ (position-a) [ (position-b)] ...I 



Deletes from FROM directory, named files or, in segment 
directories, deletes files at specified positions. 
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FORCE { CN } 
i [OFF] J 



ON forces read-access rights in FROM directory for LISTF, 
LISTSAVE, SCAN, UFDCPY, and TRECPY. OFF stops FORCE action 
(default) . 



FROM pathname 



Defines ERCM directory for subsequent commands such as COPY, 
LISTF, etc. 



LISTF [level] [FIRST] [SIZE] [PROTEC] [RWLOCK] [TYPE] 
[DATE] [PASSWD] [LSTFIL] 

Lists files and attributes at terminal (and into optional file 
called LSTFIL) . 



LISTSA VE filename [level] [FIRST] [SIZE] [PROTEC] [RWLOCK] 
[TYPE] [DATE] [PASSWD] 

Same as LISTF, with the LSTFIL option specified, but writes 
output to filename. i 



PROTEC filename [owner-access [ non-owner- access] ] 
Sets protection attributes for filename. 



SCAN filename [level] [FIRST] [LSTFIL] [SIZE] [PROTEC] 
[FWLOCK] [TYPE] [DATE] [PASSWD] 

Searches FROM directory tree for all occurrences of specified 
filename and prints requested attributes. 



SRWLOC filename lock-number 

Sets per-file read/write lock. 

TO pathname 

Defines TO directory for subsequent commands such as CREATE 
and all copying conmands. 
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TREC PY di recto ry-a [directory-b] [ f directory-c [directory-d] ] ... 
Copies directory tree(s) in FRCM directory into TO directory. 

TREDEL d i rec tory- a [d i rec tory- b] ... 

Deletes directory tree(s) in FRCM directory. 

TREPR O pathname [owner-access [ non-owner- access] ] 

Sets protection rights for directory and . contents (default 
1 0) . 

TRESFW pathname lock-number 

Sets per-file read/write lock for all files in pathname . 

UFDCP Y 

Copies entire FRCM directory into TO directory. 

UFDDEL 

Deletes entire FRCM directory. 

UFDPR O [owner-access [non-owner-access [level]]] 

Sets protection attributes for entire FROM directory. 

UFDSR W lock-nunber [n-levels] 

Sets per-file read/write lock for n-levels in FRCM directory. 
Lock-number Meaning Code 

Use system read/write lock SYS 

1 n readers OR 1 writer V0JR 

2 n readers AND 1 writer 1WNR 

3 n readers AND n writers NWNR 
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USING TAPES AND CARDS 



ACCESSING DATA ON TAPES AND CARDS 

Existing source programs resident on punched cards, magnetic tape, or 
punched paper tape can easily be read into disk files using 
PRIMOS-level utilities. In addition, the punched card and magnetic 
tape transfer utilities will translate from BCD or EBCDIC 

representation into ASCII representation saving considerable time and 
effort. 

Subroutines and other installation-dependent operations may be altered 
to conform to PRIMOS by using the editor (ED) described in Section 4. 

The general order of operations for input from a peripheral device is: 

1. Obtain exclusive use of the device (Assigning) . 

2. Transfer programs with appropriate utility. 

3. Relinquish exclusive use of the device (Unassigning) . 

Assigning a Device 

Assigning a device gives the user exclusive control over that 
peripheral device. The PRIMOS-level ASSIGN command is given from the 
terminal: 

ASSIGN device [-WAIT] 

device is a mnemonic for the appropriate peripheral: 

CRn Card Reader n (n=0,l) 

MTpdn [-ALIAS MTldn] Magnetic Tape Unit pdn (pdn=0-7) 

MTX -ALIAS MTldn Any Magnetic Tape Unit (ldn=0-7) 

PTR Paper Tape Reader 

-WAIT is an optional parameter. If included, it queues the ASSIGN 
command if the device is already in use. The assignment request 
remains in the queue until the device becomes available or the user 
types the BREAK key at the terminal; both occurrences return the user 
to PRIMOS. If the requested device is not available and the -WAIT 
parameter has not been included, the error message: 

The device is in use. (ASSIGN) 

will be printed at the terminal. 

11 - L January 1980 



SECTION 11 IDR4130 



After all I/O operations are completed, exclusive use is relinquished 
by the command: 

UNASSIGN device 

device is the same mnemonic used in the ASSIGN command. 

READING PUNCHED CARDS 

Assign use of the parallel interface card reader by: 

AS CRn -WAIT 

To read cards from the card reader, load the card deck into the device 
and enter the command: 

CRMPC deck-image [-PRINT] [-CR0] [-CR1] 

deck- image The pathname of the file into which the 

_ ^^ images are to be loaded. 

-PRINT Print card while reading. 

-CR0 Use device CR0 (default) . 

-CR1 Use device CRl. 

Source deck header control cards are set up as follows: 

Source deck Columns 1 and 2 of 
representation deck header card 

BCD $6 

EBCDIC $9 

ASCII no header card 

Reading continues until a card with $E in colunns 1 and 2 are 
encountered (end of deck); control returns to PRIMOS and the file is 
closed. If the cards are exhausted (or the reader is halted by the 
user) , control returns to PRIMOS but the file is not closed. If more 
cards are to be read into the file, the reader should be reloaded; 
reading is resuned by the command START at the terminal. 

Close the file with the command: 

CLOSE ALL 

or 

CLOSE deck-image 
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Example of card reading session: 

OK, AS CR -WAIT 

OK, CRMPC old-prograrn-l 

0K f UN CR0 

OK, 

If a serial interface card reader is used, the process is similar, with 
slightly different reader commands. 

OK, AS CARDR -WAIT 

OK, CRSER old-program-2 

OK, UN CARDR 

OK, 

CARDR may be abbreviated to CAR. 

READING PUNCHED PAPER TAPE 

First load tape into reader; then assign tape reader. Source programs 
punched on paper tape in ASCII representation can be read into a disk 
file with the Editor utility. 

OK, AS PTR -WAIT Assign tape reader 

OK, ED Invoke Editor 

INPUT 

(CR) Switch to EDIT mode 

EDIT 

INPUT (PTR) Input from tape reader 

EDIT Tape is being read 

FILE filename File input under filename 

OK, UN PTR Unassign tape reader 



MAGNETIC TAPE UTILITIES 

The Prime magnetic tape utilities (MAGNET, MAGRST and MAGSAV) allow the 
duplication of magnetic tapes, the transfer of files from disk to tape 
and vice-versa, and the transfer and translation of tapes in selected 
non-Prime formats to and from PRIMOS disk files. All mag tape 
operations done with these utilities require the assignment of at least 
one magnetic tape drive unit. 

Assigning Tape Drives 

Magnetic tape drive assignment can be set up at each installation by 
the System Administrator in one of three ways: 
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• Each user can assign a tape drive from any terminal; operator 
intervention is necessary only for processing special requests. 
This is the default mode. 

• Each user must send all assignment requests through the 
operator, who controls all access to tape drives. The operator 
then sends messages to the user terminal indicating the status 
of the assignment request. 

• Tape drive assignment from any user terminal is strictly 
forbidden. This feature is used to restrict access to tape 
drives in security-conscious environments, or when the operator 
is not available to process requests. 

The ASSIGN Command Etarmat 

Users may assign magnetic tape drives in any one of three ways: 

• By physical device number (pdn) : 

ASSIGN MTpdn [-options] 

• By logical device number (ldn): 

ASSIGN MTX -ALIAS MTldn 

• By logical device number plus characteristics: 

ASSIGN MTX -ALIAS MTldn -options 

Assigning a drive by physical device number requests that particular 
drive. If the drive is busy, -WAIT queues the request. Assigning a 
drive by logical device number says, "Give me any tape drive, and call 
it number ldn." (The -ALIAS option supplies the number.) Any free 
tape drive may then be assigned. If all devices are busy, -WAIT queues 
a request for the first free device. Assigning a drive by logical 
number plus characteristics asks for any drive that can handle a 
particular type of tape (for example, a 9-track tape at 6250 bpi) , and 
gives the drive a logical alias. In all three cases, users will be 
told which physical device has been assigned to them; they may refer 
to the device by either its physical nunber or its logical alias. 
Additionally, ASSIGN allows special requests to be made of the system 
operator; for example, removing the WRITE-ring or mounting a 
particular tape. (This version of the ASSIGN command applies only to 
mag tape drives; other peripheral devices like the paper tape reader 
(PTR) cannot be assigned with the options described here.) The command 
format, complete with optional arguments, is: 



ASSIGN (MTpdn [-ALIAS MTldn] U- option (s) ] 
| MTX -ALIAS MTldn J 
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The arguments and options are: 

Argument Description 



MTpdn 



MTX 



-ALIAS MTldn 



Mag tape (MT) unit number from to 7 , 
inclusive, pdn is the physical device number 
assigned to each drive at system startup. 
Numbers can be obtained from the system 
operator. 

Tells the operator to assign "any available 
drive"; MUST be accompanied by -ALIAS MTldn 
which assigns a number (alias) to the drive for 
reference purposes. See below. The actual 
drive assigned depends on any other options 
which appear on the command line. 



The logical 
inclusive. 



drive number, from 
ldn is a user-specified 
physical 



to 7, 

number 

drive unit; 



assigned to a particular 
used as an alias for the pdn in subseguent mag 
tape operations. Logical and physical device 
numbers can be used interchangeably in MAGNET, 
MAGSAV and MAGRST dialogs; however, to avoid 
confusion, give MAGRST/MAGSAV the logical device 
number, if you're using aliases. See Note , 
below. 



Option 



Description 



-WAIT 



^TPID id 



-RINGON 
-RINGOFF 



Indicates user is willing 
requested drive is available. 



to 



wait until 



Requests the operator to mount a particular reel 
of tape, identified by a tape id; requires 
operator intervention. id is a list of tape 
identifiers (arguments) describing a particular 
reel of tape, and/or type of tape drive (name, 
number, etc.) . Identifiers may not begin with a 
hyphen (-) which is a reserved character 
indicating the next control argument on the 
ASSIGN statement line. 

Protection rights may be specified by: 



RINGON Read and write permitted. 

or 
RINGOFF Read only; write-protection 
in effect. 
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Requires operator intervention for removal or 
replacement of write-ring. 

Particular tape density settings are requested 
-800B PI with these options. Most drives can handle 800 

-1600B PI and 1600 bpi settings. Requires operator 

-6250B PI intervention. 

-7TRK Indicates 7- or 9- track tape drive; 

-9TRK default is 9-track. Requires operation 

intervention if -7TRK is specified. 

Using the -ALIAS Option 

The -ALIAS option is useful in several general situations: 

• When you request special features and do not know which 
available drive meets the stated requirements 

• When you are writing a command file to perform mag tape 
operations and have no way of knowing which tape drive is 
available at a given time 

• When you know the actual pdn of the drive being assigned but 
prefer to give it another number, for ease of reference, or to 
avoid confusion 

Once an "alias" has been assigned, either the physical or logical 
device number can be used to refer to the drive in question in 
subsequent mag tape drive operations like MAGSAV. The logical device 
number is "mapped into", or associated with the physical device number 
in an internal table. 

With the MTX option, command files which perform mag tape operations 
can be executed independently of a particular drive's availability. 
The arbitrary number assigned the tape drive with MTX -ALIAS can be 
used in writing responses to the dialog of the utility invoked by the 
command file. 

Note 

MAGSAV and MAGRST ask the user for the device number of the 
drive on which a tape is mounted. Both dialogs assume the 
number given is a logical device number: consequently, the 
internal list of logical device numbers is searched first. If 
a match is found, M^GSAV/MAGRST will interact with the tape 
mounted on the corresponding physical drive. Suppose the user 
first assigns physical device MT0 as logical MT1, then assigns 
physical MT1 as logical MT0. If the user answers "1" to the 
"TAPE UNIT:" prompt of MAGSAV (or MAGRST), the utility assumes 
that "1" is a logical device number (ldn) . Thus, it attempts 
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to read from or write to, as the case may be, the tape mounted 
on physical device MT0, which the user previously assigned as 
logical MT1. 



USING ASSIGN 

The following examples illustrate some uses of ASSIGN. In all cases, 
the distinction between what the user can do without operator 
intervention and what must be done with operator assistance is 
indicated. 



Default Assignment 

The standard form of assignment does not require operator intervention 
on systems with the default configuration (user- privileges allowed) . 
For example: 

OK, AS MT1 

Device MTl Assigned. 

Mag tape drive MT1 is assigned. (1 is the physical device number.) If 
the device is currently assigned to another user or process, this 
message appears: 

The device is in use. (ASSIGN) 
ER! 

On systems where all mag tape requests are monitored, the request above 
would be acknowledged with the same message, but a slight delay would 
be observed. The operator has to answer each request, which results in 
a delayed response at the user terminal. 

Logical Aliases 

Logical device numbers can be assigned by the user without operator 
assistance on default privilege systems, providing that no other 
special requests are made on the same ASSIGN command line: 

OK, AS MT1 -ALIAS MT0 
Device MT1 Assigned. 

Note that the physical, not the logical, device number is returned. 

Physical device MT1 can now be referred to as logical device MT0. 
ldn' s and pdn' s are associated internally in a special table and can be 
used interchangeably. If no ldn alias is requested, the default 
logical device number is the same as the physical device number of the 
drive. The STAT DEV command lists the physical -to- logical number 
co r r espond ence : 
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OK, STAT DEV 

DEVICE USRNAM USRNW LDEVICE 
MT1 DOUROS 7 MT0 



If no logical alias had been requested, the LDEVICE entry would be 
identical to the DEVICE entry; in this case, MT1. 



Aliases in Operator Made 

Similarly, logical aliases can be requested on operator- control led 
systems. Again, the pdn of the assigned device will be displayed at 
the user's terminal with a message of this general form: 

Device MTpdn Assigned. 

pdn varies with the actual physical device chosen by the operator. 

Special Requests 

If control arguments for special requests appear on the ASSIGN command 
line, then the operator must intervene, even on systems with default 
user privileges. For example, all ASSIGN commands with the MTX option 
must be handled by the operator: 

ASSIGN MTX -ALIAS MT4 

The operator is requested to assign any available tape drive as logical 
device 4. A message is displayed at the user's terminal, indicating 
which physical drive has been assigned. 

The operator must also intervene if a user wants a tape mounted, or if 
a particular density setting is required, or if a particular drive is 
needed , ( for instance , to read a tape recorded at 6250 bpi) . For 
example: 

AS MTX -ALIAS MT3 -TPID POWER -9TRK -RINGOFF -6250 

The operator is requested to mount the "POWER" tape on a 9-track drive 
that can handle 6250 bpi. In this case, "POWER" is the name written on 
the tape reel to identify the tape and is not necessarily the recorded 
label. In addition, the user wants write-protection and is assigning 
an alias of MT3 (ldn) to whatever device the operator chooses. This 
request, if processed, might be acknowledged with this display: 

Device MT0 Assigned. 
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Operator Not Available 

If the operator is not available to handle requests, any attempt by a 
user to assign a mag tape drive will result in this message: 

OK, AS MT1 

No MagTape Assignment Permitted. (AS) 
ER! 



Operator Can' t Handle 

If any request cannot be handled by the operator for any reason, the 
following message appears at the terminal: 

OK, AS MTX -ALIAS MT0 -6250 

MagTape Assignment Request aborted (ASSIGN) 
ER! 



Improper Use of ASSIGN 

Should an improper form of the ASSIGN command be issued, an error 
message appears, as well as the proper command format, complete with 
all the options. For example: 

OK, AS MT1 -ALIS MT0 -RINGOFF 

"-ALIS" not implemented or improper use of argument. (ASSIGN) 

Usage: ASSIGN MTn [-ALIAS MTm] [<options>] 

ASSIGN MTX -ALIAS MTn [<options>] 

Options: [ -TPID <id> ] [ -7TRK I -9TRK ] [ -RINGCN I -RINGOFF ] 
[ -6250BPI | -6250 I -1600BPI | -1600 I -800BPI I -800] 
ER! 



RELEASING A TAPE DRIVE 

When a user completes a mag tape operation, the mag tape drive should 
be released for general use. Simply issue the UNASSIGN command with 
one of the indicated arguments: 

UNASSIGNI MTpdn 1 

{-ALIAS MTldn ) 

The -ALIAS option can be used to unassign a drive whether or not the 
user assigned an alias to the drive. The ldn argument value can be 
either the user-chosen logical device number, if one was assigned, or 
the default ldn, which is identical to the pdn. 



11 - 9 January 1980 



SECTION 11 IER4130 



Who Can UNASSIGN a Drive 

A tape drive can be unassigned only by: 

• The user who assigned it (on default-privileged systems) 

• The system operator 

The system operator can unassign any drive using the pdn argument; the 
"-ALIAS ldn" option can be used only if the drive is owned by (i.e., 
was previously assigned by) the operator. 

If an operator UNASSIGNs a user-dedicated tape drive, no message will 
appear at that user's terminal. Should the user subsequently attempt 
to UNASSIGN the same device an error message will be displayed. 

MAG TAPE OPERATIONS 

Each magnetic tape utility performs one or more specific functions. 

MAGNET (for both Prime and non-Prime- format files and tapes) 

• Reading files from tape to disk (with optional unblocking or 
character translation) 

• Writing files from disk to tape (with optional blocking or 
character translation) 

• Copying files from one tape to another 

• Translation from EBCDIC or BCD to ASCII during READ or WRITE 
operations (optional) 

• Copying binary files 

MAGRST (Prime-format tapes only) 

• Restoring Prime-format files, directory-trees or disk volumes 
from tape 

MAGSAV (Prime-format files only) 

• Archiving Prime-format files, directory-trees or disk volumes to 
tape 

The dialogs associated with these utilities are summarized below. For 
complete information on these utilities, see the Reference Guide, 
PRIMOS Commands. 
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THE MAGNET UTILITY 

The five MAGNET options perform the following tape operations: 

Option Function 

COPY Copies files from one tape 

to another. 

POSITION Positions tape to a file 

or record. 

QUIT Returns to PRIMOS. 

READ Reads files from tape to disk. 

WRITE Writes a file from disk to tape. 

MAGNET Requirements 

Acceptable Tapes : MAGNET accepts only unlabeled tapes with 
fixed- length records and optional blocking. They may be 7- or 9-track, 
and may be written in ASCII, BCD (7-track only) , BINARY or EBCDIC 
format. They may have a maximun of 10K bytes/tape record, and a 
maximum of 2K bytes/disk record. 

Tapes which meet these standards maybe read, written or copied with 
MAGNET. Translation from/to ASCII, BCD, BINARY and EBCDIC can be done 
during READ or WRITE operations. Record blocking/unblocking is also 
possible during these operations. 

ANSI level I volume labels of certain labeled tapes can be read with 
the LABEL corrmand. LABEL can also be used to write a label on an 
unlabeled tape. See the PRIMOS Commands Reference Guide for details. 

Read ing/WTi ting Mag Tapes : Files may be read or written (saved) to 
tape with the READ and WRITE options of MAGNET, respectively. Tapes 
created with MAGNET cannot be restored with MAGRST, so once you save 
files to tape with MAGNET WRITE, they must be read back with MAGNET 
READ. See the PRIMOS Reference Guide for complete details on the 
MAGNET READ and WRITE options. 

Copying Tapes : The COPY option allows files to be copied from one tape 
to another. No character translation is provided for during this 
operation. Tapes may also be copied in their entirety with this 
option, as explained below. 

Reading or Writing Magnetic Tape with MAGNET 

Once the tape drive has been assigned and the tape mounted, users may 
read tapes with the READ option of PRIMOS' MAGNET utility. When the 
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command MAGNET is given, an interactive dialog begins. (The same 
dialog, with the WRITE option, allows users to write tapes.) 

OK, MflGNET 

[MAGNET rev 17.1] 

OPTION: READ 

MTU# = unit- number [/tracks] 

unit-number is the number of the magnetic tape drive unit which was 
previously assigned. 

tracks is either 7 or 9; if this parameter is omitted, 9-track tape is 
assumed . 

MAGNET then asks a series of questions about the tape format. 

MTFILEfr = tape- file-number 

tape- file-number is the file number on the tape. A positive integer 
causes the tape to be rewound and then positioned to the file number; 
a causes no repositioning of the tape. 

LOGICAL RECORD SIZE = n 

This is the number of bytes/line image; normally this is 80 for a 
source program. 

BLOCKING FACTOR = blocking- factor 

blocking- factor is the number of logical records per tape record. 
(Maximum size of a tape record is 10,000 characters.) 

ASCII, BCD, BINARY, OR EBCDIC? data- repre sen tat ion 

data- re pre sen tat ion action 

ASCII Transfer 

BCD Translate to ASCII from 7-track 

tape 

BINARY Transfer verbatim 

EBCDIC Translate to ASCII 
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FULL CR PARTIAL RECORD TRANSLATION? answer 

answer is FULL or PARTIAL. The question is asked only for BCD or 
EBCDIC representations. Partial translation allows specified bytes in 
the record to be transferred to disk without translation to ASCII. The 
partial option is useful when transferring data files with binary or 
packed decimal EBCDIC data. However, almost all source programs will 
be transferred with the full option. 



OUTPUT FILENAME: filename 

filename is the name of the file in the UFD into which the magnetic 
tape is to read. If the filename already exists in the UFD, the 
question: 

OK TO DELETE OLD filename? answer 

will be asked. A NO will cause the request for an output filename to 
be repeated. A YES will cause the transfer to begin; upon completion, 
the following message will be printed out: 

DONE, tape-records RECORDS READ, disk-records DISK RECORDS OUTPUT 
OK, 

Use of the tape drive unit should then be relinquished by UN MTpdn or 
UN -ALIAS ldn. 



DUPLICATING MAGNETIC TAPES 

MAGNET can copy and read either Prime or non-Prime tapes. MAGSAV 
creates Prime- format tapes which can then be read by MAGRST. 

Copying Tapes with MAGNET : If there are two tape drives available for 
use, the COPY option of MAGNET can be used to generate duplicates of 
magnetic tapes. This option copies one tape directly to another. The 
MAGNET utility may be used for tapes in Prime or non-Prime format. 

The essential steps in the copy procedure are: 

1. Assign two magnetic tape drive units from terminal. 

2. Mount the FROM tape (original) and TO tape (blank) on their 
respective drive units. 

3. Use COPY option of MAGNET: supply FROM and TO tape unit 
numbers, starting file number and number of files to be copied, 
as requested by dialog (see below) . 

4. Dismount both tapes and unassign tape drives when EOT (end of 
tape) message is returned. 
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The MAGNET COPY dialog : The COPY option of MAGNET invokes the 
following prompts. Expected user responses are outlined opposite 
corresponding prompts. 



Prompt 
•FROM' TAPE: 

MAGNETIC TAPE UNIT NUMBER= 

STARTING FILE NUMBER= 



'TO' TAPE 
MTU NUMBER= 



STARTING FILE NUMBER= 



NUMBER OF FILES TO COPY= 



Response 

Enter number (ldn or pdn) of 
mag tape drive 

on which non-blank tape is 
mounted . 

Enter number of file to be 
copied; numbers correspond to 
order in which files appear on 
tape. 

Enter number (ldn or pdn) of 
mag tape drive unit on which 
blank tape is mounted. 

Enter position on tape where 
file will reside. 

Enter number of files to be 
copied. if copying entire 
tape, enter a large number; 
operation ceases when EOT is 
reached . 

This means the operation is 
completed. The number of 
files copied is printed and 
control returns to PRIMOS. 

Copying Tapes with MAGRST/MAGSAV : When copying tapes saved with 
MAGSAV, the MAGSAV/MAGRST utilities can be used to duplicate tapes as 
follows: 

• Assign a tape drive unit from the terminal. 

• Mount FROM (original) tape on drive unit. 

• Copy tape to files on disk using MAGRST. 

• Remove FROM tape and replace the TO (blank) tape on drive unit. 

• Transfer files from disk to TO tape using MAGSAV. 

• Dismount tape and unassign drive unit from terminal. 



DONE 
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Saving Disk Files on Tape (MAGSAV) 

The Magnetic Tape Save Utility writes PRIMOS files from disk to a 7- or 
9- track magnetic tape. Several options may be specified on the MAGSAV 
command line: 



-7TRK 
-INC 

-LONG 
-UPDT 

-VAR 



Uses 7- track 
(9-track) . 



magtape format instead of default 



Indicates incremental dunp. Only files and directories 
with DUMPED switch set to will be saved. 

(Default=save all) . 

Sets record size to 1024 words (Default=512) . 

Indicates update. DUMPED switch is set for files and 
directories saved from disk to tape. 

Allows variable- length records, up to 2048 words; 

overrides -LONG option. Improves speed of MAGSAV 

operation. If selected, the record size is printed 
after the REV stamp of the MAGSAV dialog. 



MAGSAV Dialog Summary ; The MAGSAV dialog is 
Suggested user responses are indicated. 



summa f i zed bel ow. 



Prompt 
TAPE UNIT (9 TRK) 



ENTER LOGICAL 
TAPE NUM3ER: 



TAPE NAME: 

DATE: 

REV. NO. : 

NAME OR COMMAND: 



Response 

Enter physical or logical tape drive 
number, from 0-7. If the -7 TRK option was 
not specified, (9 TRK) is displayed. 

Enter number, from 1 to n, of 

desired logical tape (see Note, below); 

tape is, then rewound and positioned. 

Specify if tape is already positioned as 

desired. 

Specify a name or identifier for this tape; 
maximum of 6 characters. 

Specify date in format: mm dd yy. Default 
(CR) is system-supplied date. 

Enter arbitrary nunber, or (CR) . 

Possible responses include: 



pathname Name of file or directory to be 
saved. 



MFD 



Saves entire disk volume. 
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* Saves current directory; up to 

13 (nested) levels can be saved 
at a time. 

$A directory [ldisk]: Changes home UFD to 
directory . If ldisk number is not 
specified, only the local disk is searched 
for directory (default) . pathnames are 
not supported. 

$1 [filename] n: Prints at terminal an 
index of files and directories saved from 
from disk to tape. Index can be written 
to a file if a filename is provided, n 
indicates number of levels in tree 
structure hierarchy to be included in 
index. 



$Q Terminates logical tape and 

returns to PRIMOS. 

$R Terminates logical tape, rewinds 

tape and returns to PRIMOS. 

$INC ON Turns incremental save option 

OFF on or off; same as -INC command 
line option, above. 



Note 

A "logical tape" results from single invocation of MAGSAV. It 
is a unique entity, with its own header, etc. It may be a 
portion of a physical tape, or a complete physical tape; or it 
may span one or more physical tapes. A single physical tape 
may contain several logical tapes, each of which is identified 
by number. 

Sample MAGSAV Session : Below is an example taken from a terminal 
session during which a disk file (TAPE. EX) was saved on tape. If a 
carriage return (CR) is given in response to the DATE and REV NO 
prompts, as shown below, the system will supply the current date and 
zero rev number. Notice that a logical device number (ldn) can be 
supplied as a response to the "TAPE UNIT" prompt as in this example. 
Either a pdn or an ldn, (if one has been assigned) , can be supplied. 

OK, AS MT1 -ALIAS MT7 
Device MT1 Assigned. 
OK, STAT DEV 

DEVICE USRNAM USRNUM LDEVICE 
MT1 DOUROS 7 MT7 
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OK, MAGSAV 

REV. 17.0 

TAPE UMIT (9 TRK): 7 

ENTER LOGICAL TAPE NUMBER: 

TAPE NAME: MAGTAP 

DATE (MM DD YY) : (CR) 

REV NO: (CR) 

NAME OR COMMAND: TAPE. EX 

NAME OR COMMAND: $Q 

OK, 



Restoring Files to Disk (MAGRST) 

The Magnetic Tape Restore Utility restores files, directory, trees and 
partitions from a magnetic tape (7- or 9-track) to a disk. All 
information is restored to the directory to which the user is currently 
attached. MAGRST can read tapes of any record size, with fixed or 
variable length records ( up to 6144 words) , making it compatible with 
MAGSAV. 

The command format is: 

MAGRST [-7TRK] (option specifies 7-track tape: default=9) 

MAGRST dialog summary : The MAGRST utility displays a series of 
questions and messages which are summarized, along with appropriate 
responses and descriptions, below: 



Prompt/Me ssag e 
YOU ARE NOT ATTACHED 
TO AN MFD 
TAPE UNIT (9 TRK): 



(TAPE NOT AT LOAD POINT) 



ENTER LOGICAL TAPE NUM3ER: 



Response/Description 

This message is returned only if 

the 

user is not attached to an MFD. 

Enter physical or logical device 
number; from 3-7. The (9 TRK) 
message is displayed if the -7 
TRK option was not specified on 
the MAGRST command line. 

This message appears if the tape 
is not positioned to the 
beginning of the tape. 

If tape is divided into several 
logical units, enter logical 
tape number from 1 to n. Tape 
is positioned to specified 
logical tape. Enter if tape 
is already positioned as 
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desired. (No action is taken in 
this case.) See also Note , 
below. 



NAME: tape- name 



DATE (MM DO YY) : tape-date 



MAGRST displays the name of the 
logical tape currently 

positioned to; names are 

provided during MAGSAV dialog. 

MAGRST displays date on tape was 
recorded. Supplied during 

MAGSAV. 



REV NO: number 



REEL NO: reel-number 



READY TO RESTORE: 



MAGRST displays arbitrary nunber 
specified during MAGSAV. 

MAGRST displays appropriate 
reel-number of tape. 

Enter one of the following 
options: 



Restores entire tape and 



YES: 



returns to PRIMOS. 



NO : Causes first prompt to be 
reissued. 



$1 [filen ame] n 
index to 
during restore, 
optionally saved 
filename. 



Prints tape 

n levels at terminal 

Index can be 

to indicated 



NW [filename] [n] : Prints n 

level index at terminal but DOES 
NOT UPDATE disk because no files 
are restored. Optionally stores 
index in filename. 



TREE NAME: 



PARTIAL: Restores only certain 
files and directories. 

Pathnames are entered in 
response to "TREE NAME:" 
prompt . 

$_ A directory [ldisk] : Changes 
home UFD to directory . If ldisk 
number is not specified, local 
disk is searched for directory . 

This prompt is returned when 
PARTIAL option is specified. 



REV. 
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Respond with one of the 
following: 

pathname: Names file or 
directory to be restored. 
Pathname should not include name 
of directory to which user was 
attached when saving file or 
directory, except when attached 
to an MFD. If, for example, a 
file, file2 , was saved from 
UFD=TOP, and its pathname is: 
T0P>MID>file2, it can be 
restored with the pathname: 
"MID>file2", but NOT with the 
pathname: "T0P>MID>file2". 

(CR) : Terminates MAGRST dialog 
by indicating end of treename 
list; tape is read, and control 
returns to PRIMOS. 

Note 
A "runaway" tape condition can occur if there is only one 
logical tape on the currently mounted reel of tape and the 
user specifies a number greater than 1 in response to the 
LOGICAL TAPE NUMBER prompt. If this happens, MAGRST will 
search endlessly for the non-existent logical tape(s) and 
will consequently be unable to read the end-of-tape marker. 
The drive must be unassigned to abort the unsuccessful 
search. 

When an unrecoverable error is encountered during an attempted MAGRST 

operation, an error message is displayed. Recoverable errors are 

logged and a total is displayed when the end of the logical or physical 
tape is reached. 
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Sample MAGRST Session : The following example represents the dialog 
necessary to restore a file from tape to disk. The file saved in the 
previous MAGSAV sample session (TAPE.EX) is used in this example also. 

OK, MAGRST 

REV. 17.0 

YOU ARE NOT ATTACHED TO AN MFD 

TAPE UNIT (9 TRK) :0 

ENTER LOGICAL TAPE NUM3ER: 1_ 

NAME: MAGTAP 

DATE (MM DD YY) : 08-31-79 

REV NO: 

REEL NO: 1 

READY TO RESTORE: PARTIAL 

TREE NAME: TAPE.EX 

TREE NAME: (CR) 

*** STARTING RESTORE *** 

*** END LOGICAL TAPE *** 

*** RESTORE COMPLETE *** 

OK, 
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INTRODUCTION 

Many Prime installations contain two or more processors connected in a 
network - a combination of communications hardware and PRIMOS software 
called PRIMENET. In a network, the processor to which the user 
terminal is connected is the local processor, while all other 
processors are considered remote . On a system using PRIMENET, you can: 



• LOGIN to a UFD on a remote system and use that CPU for 
processing. (Only terminal I/O is sent across the network.) 

• LOGIN to your local UFD, then ATTACH to directories on disk 
volumes connected to any other processor in the network, and 
access files in such directories. (File data is transmitted 
across the network; the local CPU does the processing.) 

• Use a PATHNAME with a subsystem (such as the Editor) to access a 
file on a remote disk. For example: 

ED <TPUBS>TEKMAN>B0ILERPLATE>CHAP2 

• Use FUTIL to copy a file from a remote directory into a local 
directory, avoiding the overhead of frequent remote access. For 
example : 

OK, futil 
[FUTIL rev 17.2] 

> from <tpubs>tekman>univers 

> copy s!2 

> quit 

OK, 
FUTIL is explained more fully in Section 10. 



REMOTE LOGIN 

Each processor in the system is assigned a nodename during system 
configuration. The nodename then identifies the processor for remote 
logins. (Users can determine the nodenames of remote processors by 
using the STATUS NETWORK command, explained below.) The format for 
remote logins is: 

LOGIN ufd-name [password] -ON nodename 
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If -ON nodename is omitted, an attempt is made to log into ufd-name on 
the local system only. If nodename is the name of the local node, the 
login attempt is done locally without the use of PRIMENET. 

If the LOGIN command fails for any reason (e.g., Not found, 
insufficient access rights) , the user's PRIMENET connection is broken. 
Input from the user's terminal is again processed by the local 
processor; but the user is not logged in. 

On a terminal logged in to a remote processor, the command LOGOUT logs 
out the process, breaks the remote connection over PRIMENET, and 
reconnects the terminal to its local system (not logged in) . The 
message: 

WAIT . . . 



DISCONNECTED FROM XXX 
OK, 

is displayed. All input characters typed between the LOGOUT command 
and the response OK are discarded. 



Network Status 

The STATUS NETWORK command gives the names and states of all nodes in 
the network: 

OK, status net 



RING NETWORK 




NODE 


STATE 


ENA 


**** 


ENB 


DOWN 


ENC 


UP 


END 


DOWN 


ENE 


UP 


ENG 


DOWN 


EN.D6 


DOWN 


RES. CI 


UP 



OK, 

This shows the state of a nine-node network as it would be printed for 
a local user on the ENA node. The UP state means that the node is 
configured and functioning. 
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ATTACHING TO REMOTE DIRECTORIES 

Attaching to a remote directory is the same as attaching to a local 
directory. You can give the name of the disk partition or logical disk 
number (determined from a STATUS DISKS display) within the ATTACH 
command, as in: 

ATTACH <STATISTICS>JONES 

Or you may give the UFD-name by itself. PRIMOS then searches each 
logical disk beginning with disk 0, and attaches you to the first UFD 
of that name it finds. 



Status Disks 

Users can discover the names and numbers of logical disks on remote 
systems by using the STATUS DISKS command. For example, suppose we 
wanted to attach to the UFD Tekman on node ENA, but had forgotten the 
name of the disk partition on which that UFD resided. We could 
accomplish the ATTACH as follows: 



OK, STATUS 


DISKS 




DISK 


LDEV 


PDEV 


SYS1 


SCFTWR 





3462 




SPOOLB 


1 


460 




MISCEL 


2 


71063 




D3TEST 


3 


71061 




SYSENC 


4 


460 


ENC 


SYSEND 


5 


460 


END 


TRANS 


6 


12060 


END 


TRAN52 


7 


52061 


END 


SYSENE 


12 


460 


ENE 



CPUGR1 13 12460 ENE 

CPUGR2 14 61461 ENE 

MFGTFR 15 462 ENE 

03 A 23 21460 ENA 

TPUBS 24 71061 ENA 

M168A1 25 660 ENA 

M168B1 26 10660 ENA 

OK, ATTACH <TPUBS>TEKMAN 
OK, 



In the STATUS DISKS printout, DISK is the name of the logical disk, 
LDEV is the logical disk number, PDEV is the physical disk identifier, 
and SYSN is the nodename. 
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SECTION 13 
SUBROUTINE LIBRARIES 

This section lists the subroutines available in: 

• The Applications Libraries; VAPPLB (V-mode) and APPIB (R-mode) 

• The Search and Sort Libraries: VSRTLI (V-mode) , SRTLIB 
(R-mode) , and MSORTS (R-mcde) 

• The Operating System Library 

It is meant solely as a checklist, to tell you what subroutines are 
available in these libraries. The Subroutines Reference Guide tells 
you how to use them. Thus, if you wanted to know whether a certain 
sort routine was available, you would look for it here. Having found 
it, you would consult the Subroutines Reference Guide for full details 
on how to call and use it. 

APPLICATIONS LIBRARY 

The applications library provides programmers with easy-to-use 
functions and service routines falling between very high-level 
constructs and very low-level systems routines. The applications 
library is located in UFD=LIB in the files APPLIB (R-mode programs) and 
VAPPLB (V-mode programs) . All routines in VAPPLB are pure procedure 
and may be loaded into the shared portion of a shared procedure. The 
applications library should be loaded before loading the FORTRAN 
library. 

Programs using the applications library subroutines must define the 
values of the keys used in these routines. This definition is 
performed by placing the instruction $INSERT SYSCOM>A$KEYS in each 
module which uses any of these subroutines. 

The applications routines may be used as functions or as subroutine 
calls as desired. The function usage gives additional information. 
The type of value of the function (LOGICAL, INTEGER, etc.) is 
specified for each function. 

The applications library subroutines may be grouped by their functions: 

File System 

TEMP$A, OPEN$A, OPNP$A, OPNV$A, OPVP$A, CLOS$A, RWND$A, GEND$A, TRNC$A, 
DELE$A, EXST$A, UNIT$A, RPOS$A, POSN$A, TSCN$A. 
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String Manipulation 



FILL$A, NLEN$A, MCHR$A, GCHR$A, TREE$A, TYPE$A, MSTR$A, MSUB$A, CSTR$A, 
CSUB$A, LSTR$A, ESUB$A f JSTR$A, F3UB$A, RSTR$A, RSUB$A f SSTR$A, SSUB$A 



User Query 

YSNO$A f RNAM$A, RNUM$A 

System Information 

TIME$A r CTIM$A, DTIM$A, EATE$A, EDAT$A, DOFY$A 

Conversions 

ENCD$A f CNVA$A, CNVB$A, CASE$A, FDAT$A, FEDT$A, FTIMi$A 

Mathematical Routines 
RNDI$A, RAND$A 

Parsing 

CMDL$A 

A brief description of these routines follow, in alphabetical order. 

CASE$A 

Converts a character string from uppercase to lowercase or vice versa 
and returns .TRUE, if operation succeeds. 

CLOS$A LOGICAL 

Attempts to close a file by the file unit number on which it was 
opened. Reports on success or failure of attempt. 

CMDL$A LOGICAL 

Parses a PRIMOS-like command line and returns information for each 
-keyword (and optional argunent) entry in the line (one entry is 
returned par call) . 
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CNVA$A LOGICAL 

Converts an ASCII digit string to a numerical value (INTEGER*4) for 
binary, octal, decimal, and hexadecimal numbers. Reports whether the 
conversion was made successfully or not. 

CNVB$ INTEGER*2 

Converts a number (INTEGER*4) to an ASCII digit string for binary, 
decimal, octal, and hexadecimal numbers. The function value is the 
number of digits in the string (or if the conversion is 
unsuccessful) . 



CSTR$A LOGICAL 

Compares two character strings for equality and returns .TRUE, as the 
function value if they are equal. 



CSUB$A LOGICAL 

Compares two substrings of character strings for equality and returns 
.TRUE, as the function value if they are equal. 

CTIM$A REAL*8 

Returns the CPU time since login in centiseconds (argument returned) 
and in seconds (function value). 

DATE$A REAL*8 

Returns the system date as DAY, MON DD 19YR (argument returned) and as 
MM/DD/YY (function value) . 

DELE$A LOGICAL 

Attempts to delete a file specified by the filename. If successful the 
function is .TRUE., otherwise .FALSE.. 

DOFY$A REAL*8 

Returns the day of the year as a 3-digit number (argument returned) and 
as YR.DDD (function value). The latter is suitable for printing in 
FORMAT F6.3. 
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DTIM$A REAL*8 

Returns disk time since login in cent i seconds ( argument returned) and 
in seconds (function value) . 



EDAT$A REAL*8 

Returns the date as DAY, DD MCN 19YR (argunent returned) and as 
DD/MM/YR (function value) . This is the European/military format. 



ENCD$A LOGICAL 

Encodes a value in FORTRAN floating-point print format (Fw.d) and 
reports whether the encoding was successful or not. 



EXST$A LOGICAL 

Checks for the existence of a file specified by name and reports 
whether the file exists or not. 



FDAT$A REAL*8 

Converts the date-last-modified (DATMCD) field of a directory entry to 
DAY, MCN DD YEAR (argunent returned) and MM/DD/YY (function value) . 



FEDT$A REAL*8 

Converts the date-last-modified (DATMOD) field of a directory entry to 
DAY, MON DD YEAR (argunent returned) and MM.DD.YY (function value) . 



FILL$A INTEGER 

Fills a character string with a specified ASCII character. 

FSUB$A LOGICAL 

Fills a character substring with a specified character and returns 
.TRUE, if successful. 

FTIM$A REAL*4 

Converts the time-last-modified (TIMMCD) field of a directory entry to 
HH:MM:SS (argument returned) and decimal hours (function value) . 
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GCHR$A INTEGER 

Accesses a character in a specified character position. The function 
value is the character in FORTRAN Al FORMAT (right padded with blanks) . 

GEND$A LOGICAL 

Positions a file pointer opened on a specified file unit to the 
End-of-File. The function value tells whether the positioning was 
successful or not. 



JSTR$A LOGICAL 

Right-justifies or left-justifies, or centers a string and reports 
whether the operation is successful. 



LSTR$A LOGICAL 

Locates a string within another string. The function value reports on 
whether the substring was found or not. 



LSUB$A LOGICAL 

Locates one substring within another substring. The function value 
reports on whether the substring was found or not. 



MCHR$A INTEGER 

Replaces a character in one array with a specified character from 
another. The function value is the character moved in FORTRAN Al 
FORMAT, right padded with blanks. 



MSTR$A INTEGER 

Moves one string to another string. The function value is equal to the 
number of characters moved. 



MSUB$A INTEGER 

Moves a substring in a string into a substring in another string. The 
function value is equal to the number of characters moved. 
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NLEN$A INTEGER*2 

Returns the length (not including trailing blank) of string in a 
buffer. 



OPEN$A LOGICAL 

Opens a file on a user- or system- specified file unit. The function 
value reports whether the operation was successful or not. 

OFNP$A LOGICAL 

Gets a filename from the user terminal and opens that file on a 
specified file unit. The function value reports whether the operation 
was successful or not. 

OPNV$A LOGICAL 

Opens a file on a user- or system- specified file unit, verifies the 
operation. If the file is in use the operations are retried. The 
function value reports on the ultimate success of the operations. 

OPVP$A LOGICAL 

Gets a file name from the user terminal and opens that file on a 
specified file unit. The operations are verified . If the file is in 
use the operations are re-tried. The function value reports on the 
ultimate success of the operations. 

POSN$A LOGICAL 

Positions the pointer in the file open on a specified file unit. The 
function value reports on the success of the operation. 

RAND$A REAL*8 

Updates the seed of a random number generator. The old seed is passed 
and a new seed returned. The function value is a uniform randan number 
between 0.0 and 1.0. 

RNAM$A LOGICAL 

Prints a prompt message at the terminal and accepts a name from the 
terminal. The function value reports on the validity of the name. 
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RNDI$A REAL*8 

Generates the initializing seed for a random number generator. The 
information returned is time of day in centiseconds (argument returned) 
and in seconds (function value) . 



RNUM$A LOGICAL 

Prints a prompt message at the terminal and accepts a number (octal, 
decimal, or hexadecimal) string from the terminal. If successful the 
value is returned in one of the subroutine arguments and the function 
value is .TRUE. . 



RPOS$A LOGICAL 

Returns the current absolute position of the pointer in the file opened 
on a specified file unit. The function value reports on the success of 
the operation. 



RWND$A LOGICAL 

Rewinds the file opened on the specified file unit. The function value 
reports on the success of the operation. 



TEMP $ A LOGICAL 

Opens a temporary file with a unique name in the current UFD for 
reading and writing on a user- or system- specified file unit. The 
name is returned as an argument in the subroutine call. The function 
value reports on the success of the operation. 

TIME$A REAL*8 

Returns the time of day as HR:MN:SC (argument returned) and in decimal 
hours (function value) . 

TREE$A LOGICAL 

Scans a string to check whether it is a valid pathname and, if so, 
locates the final part (filename) of the name in the string. The 
function value reports whether the test is successful or not. 

TRNC$A LOGICAL 

Truncates the file opened on a specified file unit. The function value 
reports on the success of the operation. 
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TSCN$A LOGICAL 

Scans the file system tree-structure (starting with the home directory) 
to read UFDs and segment directory entries. Each call returns the next 
file on the current level or the first file on the next lower level. 
The function value is .TRUE, until an error occurs or an end of file 
is reached. 



TYPE$A LOGICAL 

Tests a character string to see whether it can be interpreted as a 
number (binary octal, decimal, or hexadecimal) or a name. The function 
value reports whether the string meets the specified criterion. 



UNIT$A LOGICAL 

Tests whether any file is open on a specified file unit. The function 
value reports whether the unit is in use or not. 



YSNO$A LOGICAL 

Prints a question at the user terminal which can be answered YES (or 
OK) or NO. The function value is .TRUE, for YES (or OK) and .FALSE, 
for NO. Any other answer causes the question to be repeated. 
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SORT AND SEARCH LIBRARIES 

There are two classes of sorting subroutines available: disk sorts and 
in-memory sorts. Disk sorts use the mass storage devices (disks) for 
working space while the in-memory sorts put working information in the 
user's address space. For complete details on the use of these 
subroutines, see the Subroutine Reference Guide. 



Disk Sorts 

Disk sort subroutines are in the VSRTLI (V-mode) and SRTLIB (R-mode) 
libraries. VSRTLI contains the following: 

• ASCS$$ sorts or merges ASCII or binary files on any of the 12 
supported key types. 

• SUBSRT sorts a single input file on ASCII keys. It has a 
simpler calling sequence than ASCS$$. 

• SRTF$S sorts from one to twenty input files into a single output 
file. It allows specification of both input and output file 
types. 

• MRG1$S merges from one to eleven input files into a single 
output file. It allows specification of both input and output 
file types. 

The twelve supported key types are: ASCII, single-precision integer, 
single-precision real, double precision real, double- precis ion integer, 
numeric ASCII with leading separate sign, nuneric ASCII with trailing 
separate sign, packed decimal, numeric ASCII with leading embedded 
sign, numeric ASCII with trailing embedded sign, numeric ASCII 
unsigned, and ASCII with lower case letters treated as equal to upper 
case letters. SRTLIB contains the following: 

• ASCS$$ sorts on ASCII (upper and lower case) or binary keys. It 
can also merge up to ten files. 

• SUBSRT sorts a single input file on ASCII keys. It has a 
simpler calling sequence than ASCS$$. 

In-memory Sorts and Binary Search 

The subroutines listed here are contained in the library MSORTS in 
UFD=LIB. This is an R-mode library. There is, at present, no V-mode 
version. A complete discussion of these subroutines will be found in 
Reference Guide, PRIMOS Subroutines. 

See Knuth, Donald The Art of Computer Programming, vol. 3 for complete 
discussion of these types of sorts. 
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Table 13-1 lists Sorts characteristics. 



Table 13-1. Sorts Characteristics 



Sort 


Approximate 
relative running time 


Comments 


Average 


Maximum 


BUBBLE 

HEAP 

INSERT 

QUICK 

SHELL 


N**2 
23N*ln(N) 
N**2 

12N*ln(N) 

N**1.25 


26N*ln(N) 

N**2 
N**1.5 


only good for very small N 

inefficient for N<2000 

small N; very good on 
nearly ordered tables 

fastest but very slow on 
nearly ordered tables 

good for N<2000 


N is the number of entries in the table (nentry) . 



These routines all sort the table in increasing order with the key 
treated as a single, signed multiple-word integer. 

RADXEX, however, treats the key as a single, unsigned multi-word (or 
partial word) integer. For example: If the keys were 5, -1, 10, -3, 
RADXEX would sort them to: 5, 10, -3, -1 The other routines would sort 
them to: -3, -1, 5, 10 



OPERATING SYSTEM LIBRARY 

These subroutines are used mainly by PRIMOS. However, a number of them 
useful at the applications level are described in detail here. 
Complete details will be found in Reference Guide, PRIMOS Subroutines. 

File Access 

Files are structured to be accessed in either of two ways: SAM, or 
Sequential Access Method, and DAM, or Direct Access Method. SAM files 
are the most common type of file created and processed by PRIMOS. Most 
files likely to be dealt with by the user are SAM files. 

SAM Files : A SAM file consists of records threaded together with 
forward and backward pointers. Each record in the file contains a 
pointer to the beginning record address (BRA) of the file. The 
beginning record of the file contains a pointer to the file directory 



REV. 



13 



10 



IDR4130 SUBROUTINE LIBRARIES 



in which it is listed. Since records are strung together in this 
manner, they can only be accessed sequentially; the entire file must 
be searched from the beginning in order to find a record. This is time 
consuming when many randan accesses must be done. However, SAM files 
are more compact and require less disk storage space than DAM files. 
SAM files are accessed by PRIMOS commands such as ED, etc. 

DAM Files : DAM files have a multi-level index containing pointers to 
every record on the file. If the file is short, the record address 
pointers point directly to records containing data. If the file is 
long, these pointers reference other records containing a lower level 
index. Those indices in *"urn have pointers to records containing data. 

DAM structure is more suitable to rapid, random access of data than SAM 
structure. Each individual record can be referenced by a unique 
pointer connecting the record and a pointer index at the beginning of 
the file. Searching the pointer index for a particular record is 
quicker than hunting through each entire record in sequence. 

DAM files are less compact than SAM files. Thp MIDAS subsystem or user 
applications programs must be written to access them. DAM files occur 
in the MIDAS and SEG subsystems. 



Names 

In the file system calls, names are either ASCII, packed two characters 
per word, or character strings (the actual name preceded and followed 
by a single quote) . If the name length specified in a call is longer 
than the actual length of the name, the name must be followed by a 
number of trailing blanks sufficient to match the given length. 



Passwords 

Passwords can be at most six characters long. Passwords less than six 
characters must be padded with blanks for the remaining characters. 
Passwords are not restricted by filename conventions and may contain 
any characters or bit patterns. It is strongly recommended that 
passwords not contain blanks, commas, the characters 

=!'§{}[] ( ) or lowercase characters. Passwords should not 
start with a digit. If passwords contain any of the above characters 
or begin with a digit, the passwords may not be given on a PRIMOS 
command line to the ATTACH command. 



Keys and Error Codes 

All keys and error codes are specified in symbolic, rather than numeric 
form. These symbolic names are defined as PARAMETERS for FORTRAN 
programs in $INSERT files in a UFD on the master disk called SYSCOM. 
The key definition file is named KEYS.F for FORTRAN. The error 
definition file is ERRD.F. 
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Error Handling 

Errors occurring from a subroutine call causes a non-zero value of the 
argument CODE to be turned. Users should always test CODE after a call 
for non-zero values to be certain no errors are missed. Error printing 
and control are performed by the ERRPR$ subroutine: 

CALL ERRPRS (key, code, text, text-length, name,name-length) 

key Action to be taken after printing message. 

K$NRTN Exit to PRIMOS; do not allow return to calling 
program. 

K$SRTN Exit to PRIMOS; return to calling program following 
a START command. 

K$IRTN Return immediately to calling program. 

code An integer variable containing the error code 

returned by the subroutine generating the error. 

text User' s message to be printed following standard error 

message (up to 64 characters) . 

text-length Length of text in characters. 

To omit text, specify both text and text- length as 0. 

name User-specified name of program or sub-system, 

detecting or reporting the error (up to 64 
characters) . 

name- length Length of name in characters. 

To omit name , specify both name and name-length as 0. 

The message format for non-zero values of CODE is: 

standard text, user's text , if any ( name , if any) e.g., 

ILLEGAL NAME. OPENING NEWFILE (NEWWRT) 

These errors are included in the list of run- time errors in Appendix A. 
They are labeled as File System errors. 

Operating System Subroutines 

A list of all operating system subroutines with a brief description of 
their functions is given below. Subroutines marked with a bullet (•) 
are described in detail following this list. 
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ATCH$$ Attaches to a UFD and optionally makes it the hone UFD. 

CNAM$$ Changes a filename. 

COMI$$ Switches command input stream from terminal to command file 
and vice- versa. 

C0MO$$ Switches output stream from terminal to file and vice-versa. 

CREA$$ Creates a sub-UFD in the current UFD. 

ERKL$$ Reads or sets the erase and kill characters. 

GPAS$$ Returns passwords of sub-UFD in the current UFD. 

NAMEQ$ Compares filenames for equivalence. 

PRWF$$ Reads, writes, and positions pointer in a SAM or DAM file. 

RDEN$$ Reads entry in UFD. 

RDLIN$ Reads line of characters from compressed or uncompressed 
ASCII disk file. 

RDTK$$ Parses the command line, token by token. 

REST$$ Restores an R-mode memory image to user memory from a disk 
file. 

RESU$$ Restores an R-mode memory image from a file, sets initial 
values, and begins execution. An error in this call causes 
an error message to be printed automatically and then 
returns command to PRIMOS. 

SATR$$ Sets attributes (protection, date, time, etc.) in a UFD 
entry. 

SAVE$$ Saves an R-mode memory image in user memory by writing it 
into a disk file. 

SGDR$$ Positions and reads segment directory entries. 

SPAS$$ Sets the passwords in the current UFD. 

SRCH$$ Opens or closes a file. 

TEXTO$ Checks the validity of a filename. 

TSRC$$ Opens or closes a file anywhere in the PRIMOS file 
structure. 

WTLIN$ Writes a line of ASCII characters to a disk file in 
compressed format. 
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ATCH$$ 

CALL ATCH$$ (ufd-name ,name- length, logical-disk, password ,key,code) 

ufd-name Name of UFD to be attached to (if ufd-name^$HOME and 

key=0 , attachment is to home UFD) . 

name-length Length in characters of ufd-name (if ufd-name=«$HCME, 
name-length is ignored) . 

logical-disk Logical disk to searched for ufd-name when 
key=K$IMFD. 



password 



key 



logical-disk Action 
K$ALLD 
K$CURR 



Search all started-up 

logical devices. 

Search MFD of current disk. 



code 



3-word array containing the owner or non-owner 
password of ufd-name (if attaching to home UFD, 
password may be 0) . 

reference-key + set-key 

reference-key 

K$IMFD Attach to ufd-name in MFD on logical-disk. 
K$ICUR Attach to ufd-name in current UFD. 

set-key 

K$SETH Set current UFD to home after attaching. 

Returns integer-valued error code. 



CNAM$$ 

CALL CNAM$$ (old-name, old- name- length, new-name, new-name-length, 
code) 



old-name 



Name of file to be changed. 



old- name-length Number of characters in old-name . 

new-name Name to be changed to. 

new-name-length Number of characters in new-name . 

code Returns integer- valued error code. 
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Note 



CNAM$$ requires owner-rights in the current UFD. 

The names of the MFD, BOOT, BADS PT, or the packname may not be 
changed. 



FRWF$$ 

CALL PRWF$$ (read-write-key+position-key4mode, file-unit, LOC(buffer) , 
number-of-words, position-value, words- transferred, code) 



read-write-key 
K$READ 
K$WRIT 
K$POSN 

K$TRNC 

K$RPOS 

position-key 
K$PRER 

KPOSR 
K$PREA 



Action to be taken (mandatory) . 

Read number-of-wo rds from file-unit into buffer . 

Write number-of-words from buffer to file-unit . 

Set current position to value at 32-bit integer 
in position-value . 

Truncate files open on file- unit at current 
position. 

Return current positions as a 32-bit integer in 
posit ion-val ue . 

Indicates positioning (optional) . 

Move file pointer of file-unit posit ion- value 
words relative to current position; then 
perform read-wr i te-key operation. 

Performs read-wr i te-key operation then move file 
pointer of file-unit position-value words 
relative to current position. 

Move file pointer of file- unit to absolute 
position-value then perform read-wr i te-key 
operation. 



K$POSA 
If position-key is omitted, K$PRER is used. 



Perform read-write-key operation, then move 
pointer of file-unit to absolute position- value. 



mode 



omitted 



Transfer all or convenient number of 
(optional) . 

Read/write number-of-words. 



wd rds 
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K$CONV 
K$FRCW 



Read/write convenient number of words up to 
number-of-words . 

Perform write to disk from buffer before 
executing next instruction in the program. 
Increases disk I/O time. 



See Reference Guide, PRIMOS Subroutines for a 
"convenient" . 



discussion of 



file-unit 



buffer 



File unit on which the file has been opened (by 
SRCH$$, PRIMOS command, etc.) . 

Data buffer for read/write. If not needed, 
specify as LOC(0) . 



number-of words number of words to be transferred (mode=0l or 
— — — maximum number of words to be transferred 

(mode=K$CONV) . number-of-words may range from 

to 65535. 



position- value 



Relative or absolute position value (32-bit 
integer, INTEGER*4). If not needed, specify 
long- integer zero as 000000 or INTL(0). 



wo rds- transfer red The number of words actually transferred when 

read-write-key=K$READ; other keys leave this 
parameter unmodified. (INTEGER*2) . 



code 



Returns integer- valued error code. 



RESU$$ 
CALL RESU$$ (filename, name- length) 

filename Name of the file containing the memory image. 
name- length Number of characters in filename. 

SRCH$$ 

CALL SRCH$$ (action+referencehnewfile,filename,name-length, 
file- unit , file-type ,code) 

action Action to be taken (mandatory) . 

K$READ Open filename for reading on file-unit . 

K$WRIT Open filename for writing on file-unit . 
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K$REWR 
K$CLOS 
K$DELE 
K$EXST 
reference 
K$IUFD 

K$ISEG 

K$CACC 

K$GETU 

new- file 

K$NSAM 
K$NDAM 
K$NSGS 
K$NSGD 
filename 

name- length 
file-unit 

file- type 



Open filename for reading and writing on file- unit . 

Close file by filename or by file- unit . 

Delete filename . 

Check existence of filename . 

Modifies action (optional) . 

Search for filename in current UFD (this is the 
default) . 

Perform the action on the file that is a segment 
directory entry in the directory which is open on 
filename . 

Change access rights of file open on file-unit to 
action . 

Open filename on an unused file-unit selected by 
PRIMOS. The unit number is returned in file-unit . 

Specifies type of file to create if file-name does 
not already exist. 

SAM file (this is the default) . 

DAM file. 

SAM segment directory. 

DAM segment directory. 

Name of the file to be opened. If referenced $ISEG, 
filename is a file unit on which a segment directory 
is already open. 

Number of characters of filename. 

File unit number on which file is to be opened or 
closed. 

Returns type of file opened. If call does not open 
file, its value is unchanged. The values are 
integers. 

SAM file 

1 DAM file 

2 SAM segment directory 

3 DAM segment directory 

4 UFD 
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code 



Returns an integer- valued error code. 
NOte 



A UFD may be opened only for reading. 

A UFD cannot be deleted unless it is empty. 

A segment directory cannot be deleted unless it is of length 0. 

TSRC$$ 

CALL TSRC$$ (actionfnew-file, pathname, file-unit, character- 
position, code) 



action 
K$READ 
K$WRIT 
K$RDWR 

K$DELE 

K$EXST 

new- file 

K$NSAM 
K$NDAM 
K$NSGS 
K$NSGD 
pathname 

file-unit 



Action to be taken (mandatory) . 

Open pathname for reading on file-unit . 

Open pathname for writing on file-unit . 

Open pathname for reading and writing on 
file-unit . 

Delete file pathname . 

Check on existence of pathname . 

Specifies type of file to create if pathname 
does not already exist. 

SAM file (this is the default) . 

DAM file. 

SAM segment directory. 

DAM segment directory. 

A specification of any file in any directory 
or subdirectory stored in array pathname 
packed two characters per word. 

File unit number on which the file is to be 
opened or deleted . The file-unit is closed 
before any action is taken. 



character- position A two-element integer array. 

word 1 of entry: the first character in the 
array that is part of the pathname (count 
starts at 0) returns: one past the last 
character that was part of the pathname. 
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word 2 - the number of characters in the 
pathname . 

file- type Returns type of file opened. If call does not 

open file, its value is unchanged. The values 
are integers. 

SAM file 

1 DAM file 

2 SAM segment directory 

3 DAM segment directory 

4 UFD 

code returns an integer valued error code 

Note 

TSRC$$ always closes the file unit, then attaches to the user's 
home UFD before attempting any action. 
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SECTION 14 
USING RDY AND ABBREV 

Users can modify the PRIMOS command environment in three ways: 

• They can use the RDY command to choose the form of prompts to be 
displayed at their terminal during an interactive session or in 

a command file. 

• They can use the ABBREV command to define their own 
abbreviations for PRIMOS commands, and to use those 
abbreviations during interactive sessions. 

• They can define their own condition-handling routines (on-units) 
to supplement or replace system-supplied ones. 

The use of RDY and ABBREV are explained in this section. The condition 
mechanism and its use are explained in the next section. 

CHANGING THE PROMPT MESSAGE 

In addition to its normal 0K y and mi_ prompts, PRIMOS also supplies a 
long form of prompt message which displays the time, the amount (in 
seconds) of CPU time and I/O time used since the last prompt, and the 
user's stack level. (The stack level is only displayed if it is 
greater than 1; most users don't need to worry about it.) 

Users can change the form of prompt message displayed at their terminal 
by giving the RDY command. 

Command Function 

RDY -LONG Sets the terminal to the long form 

of prompt. 

RDY -BRIEF Returns it to the standard "OK,". 

RDY -OFF Suppresses prompts entirely. 

RDY -ON Re-enables prompts to the previous level of 

verbosity (long or brief) . 

RDY Prints a single long-form prompt message. 

For example: 

OK, RDY -LONG 

OK 09:21:29 0.284 0.324 
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RDY -OFF 

RDY -ON 

OK 09:21:43 0.036 0.000 

RDY -BRIEF 

OK, 



CREATING AND USING ABBREVIATIONS (ABBREV) 

The PRIMOS command ABBREV allows you to create your own abbreviations 
for use in PRIMOS command lines. Its form is: 

ABBREV [pathname] [options] 

To use ABBREV, you: 

• Create an empty abbreviation file. 

• Define abbreviations within the file. 

• Invoke ABBREV to activate the file during any work session in 
which you want to use your abbreviations. 



When an abbreviation file is activated, PRIMOS calls its abbreviation 
processor to scan each PRIMOS command entered from the user's terminal. 
The abbreviation processor checks each word against the active 
abbreviation file, expands all abbreviations to their full defined 
form, then passes on the commands to the standard command processor. 
You can modify your abbreviation file at any time; but you can use it 
only for interactive sessions. Abbreviations will not be expanded in 
command files. Once your abbreviation file is activated, it remains 
active until you give the ABBREV -OFF command or log out. 

Creating an Abbreviation File 

Invoke the ABBREV command with the -CREATE option, giving a pathname 
which names and locates the new file. For example: 

ABBREV MY_UFD>MY_UFD.ABBREV -CREATE 

This command creates and activates an empty abbreviation file. 
Therefore, the file specified must not already exist. 

Defining Abbreviations 

Abbreviations are defined and put into the abbreviation file by the 
-ADD option of the ABBREV command. This option has the form: 

ABBREV [pathname] -ADD name value 
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where name is the abbreviation and value is the commands and/or 
arguments the abbreviation specifies. For example: 

ABBREV -ADD JD JOB DISPLAY 

This example enters the abbreviation "JD" in the user's abbreviation 
file, and defines it as standing for the command "JOB" plus the option 
"-DISPLAY." Whenever this abbreviation file is activated during a work 
session at a terminal, typing "JD" at that terminal will be equivalent 
to typing "JOB -DISPLAY". 

Note 

Beware of defining abbreviations identical to PRIMOS 
abbreviations. The abbreviation processor will give your 
abbreviation precedence. Therefore, you won't be able to use 
the PRIMOS abbreviation while your abbreviation file is active. 



Activating an Abbreviation File 

ABBREV pathname [-ON] 

activates an existing abbreviation file. PRIMOS loads the abbreviation 
table from the specified file and checks each word typed at the 
terminal against the abbreviations in the file before giving it to the 
command processor, expanding the abbreviations it finds into their full 
form. 



Using Variables in Abbreviations 

You can define variables within an abbreviation by using numerals 
flanked by ABBREV' s escape character, %. The symbol "%1%" stands for 
the first word following the abbreviation, %2% stands for the second 
word, and so on. (Currently, up to nine variable words are allowed.) 
This feature is particularly handy for commands naming files. For 
example, defining an abbreviation by the command: 

ABBREV -ADD F %1% %2% -L %2%.LIST.%1% -XREF -64V -DEBUG 
would allow the abbreviation processor to translate the command: 

F FTN FOO 
into the command: 

FTN FOO -L FOO. LIST. FTN -XREF -64V -DEBUG 
Similarly, 

F F77 FOO 
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would become 

F77 FOO -L F0O.LIST.F77 -XREF ^64V -DEBUG 

Other Options ; ABBREV has options for refining definitions, changing 
or deleting definitions, etc. Four of common use are: 



Command 
ABBREV -OFF 
ABBREV [pathname] -ON 

ABBREV [pathname] -DELETE 

abbrev-1 [...abbrev -n] 
ABBREV [pathname] -LIST 



Function 

Deactivates abbreviation file. 

Reactivates file. If pathname is 
not supplied, previous pathname is 
used. 

Deletes the named abbreviations 
from the file. 



Lists the contents of the file. 



For a full list of options and their uses, see the PRIMOS Commands 
Reference Guide. 
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SECTION 15 
USING THE CONDITION MECHANISM 



INTRODUCTION 

PRIMOS has a condition mechanism which is activated when any executing 
process encounters certain unusual events. These events (or 
conditions) fall into three categories: 

• Software-puzzling situations: end of file encountered while 
reading data, illegal addresses, etc. 

• Hardware and arithmetic exceptions: numbers too large or too 
small for the computer to handle, attempts to divide by zero, 
program too large for its allotted space, etc. 

• External occurrences: situations not directly controlled by the 
executing process, such as the use of the break key from the 
user's terminal 

More than 30 PRIMOS-defined conditions exist. Some examples are: 

Condition Definition 

ACCESS_VT0IATION$ Process has attempted to read, 

write or execute into a segment 
to which it has no access for 
that function. 

ARITH$ Arithmetic exception. 

STACK_OVF$ Process has overflowed its stack 

segment . 

QUIT$ User has hit break key on 

terminal. 

ILLEGAL_INST$ Process has tried to execute an 

illegal instruction. 

ENDFILE (file) End of file encountered while 

reading a PLA file. 

For a complete list of these conditions, see the Subroutines Reference 
Guide. 
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USING THE CONDITION MECHANISM 



The condition mechanism's goal is either to repair the problem and 
restart the program, or to terminate the program in an orderly mariner. 
To achieve this goal, the condition mechanism activates diagnostic or 
remedial subroutines (or PL/I begin blocks) called on- units . 

Users writing in FORTRAN IV, FORTRAN 77, PL/I, COBOL, or PMA can define 
their own on-units within the procedures for which they're intended. 
However, all users are automatically protected by PRIMOS' system 
on-units. When an error condition occurs, the condition mechanism 
looks for on-units within the executing procedure. If it finds none, 
or if the procedure's on-units call for further help, the condition 
mechanism searches first through any calling procedures' on-units and 
then through the system's on-units, activating the first appropriate 
on-unit it finds. 



THE SYSTEM DEFAULT ON-UNIT 

Of all the system on-units, the system default on-unit is the one most 
likely to be encountered by the user. This on-unit prints the 
following message at the user's terminal, then returns the user to 
PRIMOS command level: 

Error: condition "condition" raised at "address" 
[extra information] 

The user may then take any one of the following actions: 

• Give the START command. The condition mechanism will try to 
resume running the program from the point at which the condition 
was raised. 

• Give the DMSTK command. This will print (at the terminal or 
into a file, as the user prefers) a stack dump, which traces the 
sequence of calls and returns by which the program reached its 
current state. If you are familiar with PRIME machine 
architecture, you may find that this command gives you enough 
information to solve your problem. (For details, see the PRIMOS 
Command Reference Guide.) The user may START a program again 
after dumping the stack. 

• Give the DBG command to invoke the source- level debugger. Then 
re-run the program under DBG. If the DMSTK command didn't 
provide enough information to solve the problem, this is 
probably the best course of action to take. (For information on 
how to use the debugger, see the section on "Debugging" in this 
guide.) 

• Give the RLS command to release the errant program. You will 
remain at PRIMOS command level and can give any PRIMOS command 
you choose. 
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Note 



If the system default on-unit is invoked for a process running 
as a phantom or batch job, the condition mechanism prints the 
error message into the job's command output file and then logs 
the process out. 



ON-UNIT ACTIONS 
On-units can: 

• Terminate the program via a non-local GOTO, passing control back 
to the main program, so that it can call EXIT and return to 
PRIMOS level. 

• Run diagnostic routines, then terminate the program (as above) . 

• Repair the problem which caused the error condition and have the 
program resume execution from the point of interrupt. 

• Ignore the error condition and resume running the program. 

• Transfer control to some predetermined spot in the program, 
possibly in a different procedure from the one which raised the 
error condition. 

• "Continue to signal", passing control back to the condition 
mechanism and telling it to hunt for another on-unit. 

• Print messages, then do any of the above. 

• Print messages and/or run diagnostic routines, then transfer 
control back to the user at the terminal (as the system default 
on-unit does) . 



WRITING ON-UNITS 

User-written on-units have the advantage of being tailored to the 
procedures for which they are written. Since on-units have the same 
range of action as any subroutine, they can be as elaborate or as 
simple as required. On-units can even turn some error conditions into 
advantages: "ON ENDFILE CALL some-subroutine" can be an efficient way 
of terminating an indefinite-length input loop. 

Within any procedure, users can define on-units for as many conditions 
as circumstances dictate. On-units can also be defined to handle 
conditions not normally recognized by PRIMOS: one subroutine (created 
by a call to SIGNL$ or SGNL$F) signals the condition when it occurs and 
another (created by a call to MKONU$ or MKON$F) acts as on-unit. 
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PRIMOS provides the following subroutines for users wishing to create 
their own on-units: 

Subroutine Function 

MKONU$ Called by a procedure when it wishes to 

create an on-unit. 

MKON$F A FCRTRAN-specific version of MKONU$. 

SIGNL$,SGNL$F Called to raise a condition. 

CNSIG$ Called by an on-unit to pass control back 

to the condition mechanism. 

RVONU$,RVON$F Called by a procedure to revert (disable) 

an on-unit. 

MKLB$F,PL1$NL Used in FORTRAN programs to enable 

on-units to perform non-local GOTO's. 

Information on how to use these subroutines is given in the Subroutines 
Reference Guide. 

When writing on-units, the following rules must be observed: 

• On-units can hand on control in one of three ways: by calling 
another procedure, by a local or non-local GOTO, or by returning 
to the calling procedure. (They may not call EXIT, though they 
may GO TO a point in the main program which does so.) 

• They may set error codes as return parameters, print error 
messages, or signal other error conditions. But they may not 
call ERRRTN or use ERRPR$ with any but the immediate-return key 
(K$IRTN) . 

• Programs containing on-units must be compiled in V-mode or 
I-mode. 



SCOPE OF ON-UNITS 

On-units are usually defined at the beginning of a program or 
subroutine; but they may be defined at any point within the program. 
When the program reaches the point at which the on-unit is defined, 
(i.e., a call to MKONU$ or MKON$F) the on-unit is said to be set . 
However, the on-unit does not execute at this point. It does not 
execute unless the condition to which it responds is raised. An 
on-unit remains set until one of three things happens: 

• The procedure within which the on-unit was defined returns 
(ends) . 
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• A new on-unit for the condition is defined. 

• The on-unit is r -verted (disabled) by a call to RVONU$ or 
RVON$F. 

Thus, if an on-unit for the condition ARITH$ is defined at the 
beginning of a program, it remains in effect throughout the program, 
unless it is reverted or some other on-unit for ARITH$ is defined later 
in the program. If a subroutine within that program defines its own 
on-unit for ARITH$, then that on-unit takes precedence (but only while 
the subroutine is executing) . Each call to the subroutine 
re-establishes its on-unit; each return from the subroutine reverts 
the new on-unit and re-establishes the on-unit defined in the main 
program. (If no on-unit is defined within the main program, then 
PRIMOS" on-units are in effect when the main program is running.) 



A FORTRAN EXAMPLE 

Suppose you have a program which contains a subroutine called UPDATE 
that periodically updates journal entries, headers, etc. Once this 
subroutine is started, you want it to finish; a QUIT in the middle 
could foul up your bookkeeping, write a subroutine called NOQUIT which 
responds to QUITs by printing a message at the terminal but otherwise 
ignoring the QUIT: 

SUBROUTINE NOQUIT (CP) /*This will be the on-unit 
INTEGER*4 CP /*CP=pD inter to condition frame for QUIT$ 

C 

COMMON/COM/NAME /*A variable used by UPDATE 

CALL TNOU ('Sorry, quits not allowed during update', 38) 

CALL TNOUA ('Currently processing record ', 28) 

CALL TNOU (NAME, 6) 

RETURN /*Return to UPDATE at point where quit occurred 

END 

Define NOQUIT as an external procedure within subroutine UPDATE, and 
establish it as an on-unit via the subroutine MKON$F. Note that if 
UPDATE (or any subroutine that calls MKONU$ or MKON$F) is to be 
compiled with the FTN compiler, it must obey the following rules: 

• It must include a STACK HEADER 34 specification. 

• It must be compiled using the -SPO option. This option allows 
allocation of the stack header space needed by the on-unit, but 
suppresses some error testing. Therefore, we advise that you 
first compile the on-units without the -SPO option, in order to 
test for coding errors that -SPO would ignore, before doing the 
actual compilation with -SPO. 

• Since the -SPO option activates the DCLVAR option, the 
subroutine may not contain undeclared variables. 
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• It must not contain common blocks with names of five letters 
followed by a dollar sign (xxxxx$) . 

SUBROUTINE UPDATE 
C 

EXTERNAL NOQUIT 

STACK HEADER 34 /*Provides stack space for on-unit 

COMMON/COM/NAME /*On-unit reports the value of this 

/♦variable 
INTEGER*2 NAME 
CALL MK0N$F ('QUITS', 5, NOQUIT) 

/♦Parameters are: 

/* condition-name (defined by PRIMOS) 

/* length of condition name 

/* name of on-unit subroutine 

C 

C 

C ...body of subroutine would go here... 

C 

C 

C 

RETURN /*At this point, NOQUIT's authority ceases. 

END 



A PL/I EXAMPLE 

The hypothetical problem: provide a program with an on-unit for the 
condition POINTER$_FAULT that will fix a faulting pointer to point at a 
(possibly long- integer) zero, and retry the instruction that faulted. 

A possible solution: 

problem: proc; 

del mkonu$ entry (char(*) var, entry) options (shortcall (18)), 
long zero fixed bin(31) static init (0), 
ptr_fault_ char (14) var static init ('POINTER_FAULT$'); 

$INSERT dcl_for_ffh 
$INSERT dcl_for_cfh 

/* Set up the on-unit for POINTER_FAULT$. */ 

call mkonu$ (ptr_fault_, ptr_handler) ; 

/* Now perform the computations that might cause pointer- faults. */ 
/* Having done them, return. */ 

return; 
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/* On-unit for POINTER_FAULT$. Correct the faulting 
pointer to point at long zero, and restart at the 
point of interruption. */ 

ptr_handler: proc (cp) ; 

del cp ptr; /*po inter to cfh */ 

del msp ptr; /* local copy of machine state ptr */ 
del based_ptr ptr based; 

msp = cp -> cfh.ms_ptr; 

msp -> ffh.fault_addr -> based_ptr = addr (longj; 

/* The above uses the hardware-saved pointer to the faulting 
pointer, which is found in the machine-state ffh, to reset 
the bad pointer. We then simply return, causing the 
instruction to be re-executed. */ 

return; 

end; /* ptr_handler */ 

end; /* problem */ 
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APPENDIX A 
GLOSSARY OF PRIME CCNCEPTS AND CONVENTIONS 



The following is a glossary of concepts and conventions basic to Prime 
computers, the PRIMOS operating system, and the file system. 

• binary file 

A translation of a source file generated by a language translator (FTN, 
PL1G, F77, COBOL, PMA, RPG) . Such files are in the format required as 
input to the loaders. Also called "object file". 



• byte 

8 bits; 1 ASCII character. 

• condition mechanism 

A PRIMOS facility which responds to conditions that would normally 
cause program termination. Rather than terminating the program 
immediately, the condition mechanism activates an on-unit to take some 
diagnostic or remedial action. A list of conditions handled by PRIMOS* 
condition mechanism is given in the Subroutine Reference Guide. 



• CPU 

Central Processor Unit (the Prime computer proper as distinct from 
peripheral devices or main memory) . 



• current directory 

A temporary working directory explained in the discussion on Home vs 
Current Directories in Section 2. 



• directory 

A file directory; a special kind of file containing a list of 
filenames and/or other directories, along with information on their 
characteristics and location. MFDs, UFDs, and subdirectories 
(sub-UFDs) are all directories. (Also see segment directory .) 
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• directory name 

The file name of a directory. 

• external command 

A PRIMOS command existing as a runfile in the command directory 
(CMDN33) . It is invoked by name, and executes in user address space. 
No system-wide abbreviations exist for external commands. Users may 
define abbreviations for external commands by using the ABBREV command. 



• file 

An organized collection of information stored on a disk (or a 
peripheral storage medium such as tape) . Each file has an identifying 
label called a filename. 



• filename 

A sequence of 32 or fewer characters which names a file or a directory. 
Within any directory, each filename is unique. Directory names and a 
filename may be combined into a pathname . Mast commands accept a 
pathname wherever a filename is required. 

Filenames may contain only the following characters: 

A-Z, 0-9, _#$-.*& 

The first character of a filename must not be numeric. On some devices 
underscore (_) prints as backarrow (<-). 

• filename conventions 

Prefixes indicate various types of files. These conventions are 
established by the compilers and loaders, or by common use, and not by 
PRIMOS itself. 

B_filename Binary (Object) file 

C filename Command input file 

L_filename Listing file 

M_filename Load map file 

0_filename Command output file 

PH filename Phantom command file 
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filename Source file or text file 

♦filename SAVED (Executable) R-mode runfile 

# filename SAVED (Executable) V-mode runfile 



• file-unit 

A number between and 127 ('177, or octal 177)) assigned as a 
pseudonym to each open file by PRIMOS. This nunber may be given in 
place of a filename in certain commands, such as CLOSE. PRIMOS-level 
internal commands require octal values. Each user is guaranteed at 
least 16 file units at a time. The maximum number of units that a user 
may have open simultaneously varies per installation; the default is 
128. PRIMOS always reserves units and 127 for its own use. 

• file protection keys 
See keys, file protection . 

• home directory 

The user's main working directory, initially the login directory. A 
different directory may be selected with the ATTACH command. See the 
discussion on Home vs Current Directories in Section 2. 



• identity 

The addressing mode plus its associated repertoire of computer 
instructions. Programs compiled in 32R or 64R mode execute in the 
R-identity; programs compiled in 64V mode execute in the V-identity. 
Programs compiled in 321 mode execute in the I-identity. R-identity, 
V-identity and I-identity are also called R-mode, V-mode, and I-mode. 

• internal command 

A command that executes in PRIMOS address space. Does not overwrite 
the user memory image. PRIMOS-defined abbreviations exist for internal 
commands. 
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• keys, file protection 

Specify file protection, as in the PROTEC command. 

No access 

1 Read 

2 Write 

3 Read/Write 

4 Delete and truncate 

5 Delete, truncate and read 

6 Delete, truncate and write 

7 All rights 

• LDEV 

Logical disk device number as printed by the command STATUE DISKS. 
(See ldisk.) 



• ldisk 

A parameter to be replaced by the logical unit number (octal) of a disk 
volume. It is determined when the disk is brought up by a STARTUP or 
AEDISK command. Printed as IDEV by STATUS DISKS. 

• logical disk 

A disk v o lume that has been assigned a logical disk number by the 
operator or during system startup. 



• MED 

The Master File Directory. A special directory that contains the names 
of the UFDs on a particular disk or partition. There is one MFD for 
each logical disk. 



• mode 

An addressing scheme. The mode used determines the construction of the 
computer instructions by a compiler or assembler. (See identity .) 



• nodename 

Name of system on a network; assigned when local PRIMOS system is 
built or configured. 



REV. A - 4 



IDR4130 GLOSSARY 



number representations 



xxxxx 


Decimal 


'xxxxx 


Octal 


$ xxxxx 


Hexadecimal 



• object file 
See binary file , 

• on-unit 

A begin block (in PL/I) or subroutine (in FORTRAN, COBOL, or PL/I) 
which is activated by the condition mechanism to handle error 
conditions. PRIM06 has on-units for all conditions it recognizes. 
Users may also define on-units within any procedure they write. 
User-written on-units take precedence over system ones. 



• open 

Active state of a file-unit. A command or program opens a file-unit in 
order to read or write it. 



• output stream 

Output from the computer that would usually be printed at a terminal 
during command execution, but which is also written to a file if 
COMOuTPUT command was given. 



• packname 

See volLme-name . 

• page 

A block of 1024 16-bit words within a segment (512 words on Prime 300) . 

• partition 

A portion [or all] of a multihead disk pack. Each partition is treated 
by miMOS as a separate physical device. Partitions are an integral 
number of heads in size, offset an even number of heads from the first 
head. A volume occupies a partition, and a "partition of a disk" and a 
"volume of files" are actually the same thing. 
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pathname 



A multi-part name which uniquely specifies a particular file (or 
directory) within a file system tree. A pathname (also called 
treename) gives a path from the disk volune, through directory and 
subdirectories, to a particular file or directory. See the discussion 
on Pathnames in Section 2. 



• PDEV 

Physical disk unit number as printed by STATUS DISKS. (See pdisk.) 



• pdisk 

A parameter to be replaced by a physical disk unit number. Needed only 
for operator commands. 



• phantom user 

A process running independently of a terminal, under the control of a 
command file. 



• procedure 

In FORTRAN, a subroutine or function. In PL/I, any subroutine, 
function, or program. (In PL/I, procedures may contain other 
procedures.) In COBOL, the term usually refers to one or more related 
paragraphs or sections within the Procedure Division. Procedures 
direct the computer to perform a particular operation or a series of 
operations. 



• process 

A particular program running in a particular address space. 

• reserved characters 

The following characters are reserved by PRIMOS for special uses. They 
may not be used in file names. 

()*[]! { } ~ " ? : ~ I <>§+'% \ (delete or rubout) 
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• runfile 

Executable version of a program, consisting of the loaded binary' file, 
subroutines and library entries used by the program, COMMON areas, 
initial settings, etc. (Created using LOAD or SEG.) 



• SEG 

Prime's segmented loading utility. 



• segment 

A 65,536-word block of address space. 



• segment directory 

A special form of directory used in direct-access file operations. Not 
to be confused with directory, which means "file directory". 



• segno 
Segment number. 

• source file 

A file containing programming language statements in the format 
required by the appropriate compiler or assembler. 

• subdirectory 

A directory that is in a UFD or another subdirectory. 

• sub-UFD 

Same as subdirectory . 

• treename 

A synonym for pathname . 

• UFD 

A User File Directory, one of the Directories listed in the MFD of a 
vol une . It may be used as a LOGIN name. 
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• unit 

See file- unit . 

• volume 

A self-sufficient unit of disk storage, including an MFD, a disk record 
availability table, and associated files and directories. A volume may 
occupy a complete disk pack or be a partition within a multi-head disk 
pack. 



• volume-name 

A sequence of 6 or fewer characters labeling a volume. The name is 
assigned during formatting (by MAKE) . The STATUS DISKS command uses 
this name in its DISK column to identify the disk. 



• word 

As a unit of address space, two bytes or 16 bits. 
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APPENDIX B 
SYSTEM DEFAULTS AND CONSTANTS 



TERMINAL 

full duplex 
X-ONA-OFF disabled 



EDITOR (ED) 

INPUT (TTY) 

LINESZ 144 

MODE NCKPAR 

MODE NCOLUMN 

MODE NCOUNT 

MODE NNUMBER 

MODE NPROMPT 

MODE PRALL 

VERIFY 
Symbols 

BLANKS t 

COUNTER @ 

CPROMPT $ 

DPROMPT & 

ERASE " 

ESCAPE * 

KILL ? 

SEMICO ; end of line or command 

TAB \ 

WILD ! 



SEGMENTED-LOADER (SEG) 

Loading address: current TOP+1 in 

current procedure segment 
Stack size: '6000 words 
Library: PFTNLB and IFTNLB libraries 



VIRTUAL LOADER (LOAD) 

Memory Location: '122770 - '144000 
Loading address: current *PBRK value 
Library: FTNLIB FORTRAN library 
MODE: D32R 
Sector Zero Base Area: 

Base start at location '200 

Base range '600 words 
COMMON: Top = '077777 
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EXECUTION 

A-register value 

B- register value 

X-register value 

Program start address *1000 
Bits 4-6 of Keys: 

000 16K, sector-address 

001 32K, sec tor- address 

010 64K, relative-address 

011 32K, relative- address 
110 64K, segmented-address 



CONTROL-P or BREAK 



FRIMOS 
ERASE 
INTERRUPT 
KILL 
Files: 

created with protection 
owner all access rights (7) 
non- owner no access rights (0) 
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APPENDIX C 
ASCII CHARACTER SET 



The standard character set used by Prime is the ANSI, ASCII 7-bit set, 
shown in Tables C-l and C-2. This character set conforms to ANSI 
X3. 4-1968. (1963 variances are noted.) 

PRIME USAGE 

Prime hardware and software uses standard ASCII for communications with 
devices. The following points are particularly important to Prime 
usage. 



Output Parity is normally transmitted as a zero (space) unless 
the device requires otherwise, in which case software will 
compute transmitted parity. Some controllers (e.g., MLC) may 
have hardware to assist in parity generations. 

Input Parity is ignored by hardware and by standard software. 
Input drivers are responsible for making the parity bit suit the 
host software requirements. Some controllers (e.g., MDC) may 
assist in parity error detection. 

The Prime internal standard for the parity bit is one, i.e., '200 
is added to the octal value. 



KEYBOARD INPUT 

Non-printing characters may be entered into text with the logical 
escape character " and the octal value. The character is interpreted 
by output devices according to their hardware. (For example, typing 
"207 will enter one character into the text.) 

is interpreted as a .BREAK. 

is interpreted as a newline (.NL.) 

is interpreted as a character erase 

is interpreted as line kill 

is interpreted as a logical tab (Editor) 



CTRL-P 


("220) 


.CR. 


C215) 


ii 


(•242) 


7 


('277) 


\ 


C334) 
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Table C-l. ASCII Character Set (Non-Printing) 



Octal 


ASCII 


Value 


Char 


200 


NULL 


201 


SOH 


202 


STX 


203 


BTX 


204 


EOT 


205 


ENQ 


206 


ACK 


207 


BEL 


210 


BS 


211 


HT 


212 


LF 


213 


VT 


214 


FF 


215 


CR 


216 


SO 


217 


SI 


220 


DLE 


221 


DC1 


222 


DC2 


223 


DC3 


224 


DC4 


225 


NAK 


226 


SYN 


227 


ETB 


230 


CAN 


231 


EM 


232 


SUB 


233 


ESC 


234 


FS 


235 


GS 


236 


RS 


237 


US 



Comments/Prime Usage 

Null character - filler 

Start of header (communications) 

Start of text (communications) 

End of text communications 

End of transmission (communications) 

End of I.D. (communications) 

Acknowledge affirmative (communications) 

Audible alarm (bell) 

Back space one position (carriage control) 

Physical horizontal tab 

Line feed; ignored as terminal input 

Physical vertical tab (carriage control) 

Form feed (carriage control) 

Carriage return (carriage control) (1) 

RRS-red ribbon shift 

BRS-black ribboon shift 

RCP-relative copy (2) 

RHT-relative horizontal tab (3) 

HLF-half line feed forward (carriage control) 

RVT-relative vertical tab (4) 

HLR-half line feed reverse (carriage control) 

Negative acknowledgement (communications) 

Synchronocity (communications) 

End of transmission block (communications) 

Cancel 

End of Medium 

Substitute 

Escape 

File separator 

Group separator 

Record separator 

Unit separator 



Control 
Char 

-§ 
"A 
~B 
*C 
t> 
"■E 
~F 
"G 
~H 
'I 
~J 

~L 
*M 
~N 
~0 
"P 
~Q 
"R 
"S 
~T 
~U 
"V 
~W 

"X 
«v 

~Z 
"I 
*\ 



Notes 

1. Interpreted as .NL. at the terminal. 

2. .BREAK, at terminal. Relative copy in file; next byte 
specifies number of bytes to copy from corresponding position 
of preceeding line. 

3. Next byte specifies number of spaces to insert. 

4. Next byte specifies number of lines to insert. 
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Table C-2. ASCII Character Set (Printing) 



Octal 


ASCII 


OCTAL 


ASCII 


OCTAL 


ASCII 


Value 


Character 


Value 


CHaracter 


Value 


Character 


240 


.SP^(l) 


300 


§ 


340 


x (9) 


241 


j 




301 


A 


341 


a 


242 


ii 


(2) 


302 


B 


342 


b 


243 


# 


(3) 


303 


C 


343 


c 


244 


$ 




304 


D 


344 


d 


245 


% 




305 


E 


345 


e 


246 


& 




306 


F 


346 


f 


247 


i 


(4) 


307 


G 


347 


g 


250 


( 




310 


H 


350 


h 


251 


) 




311 


I 


351 


i 


252 


* 




312 


J 


352 


j 


253 


+ 




313 


K 


353 


k 


254 


f 


(5) 


314 


L 


354 


1 


255 


- 




315 


M 


355 


m 


256 


• 




316 


N 


356 


n 


257 


/ 




317 





357 


o 


260 







320 


P 


360 


P 


261 


1 




321 


Q 


361 


q 


262 


2 




322 


R 


362 


r 


263 


3 




323 


S 


363 


s 


264 


4 




324 


T 


364 


t 


265 


5 




325 


U 


365 


u 


266 


6 




326 


V 


366 


V 


267 


7 




327 


w 


367 


w 


270 


8 




330 


X 


370 


X 


271 


9 




331 


Y 


371 


y 


272 


• 




332 


Z 


372 


z 


273 


9 




333 


[ 


373 


{ 


274 


< 




334 


\ 


374 


1 


275 


= 




335 


] 


375 


} 


276 


> 




336 


"(7) 


376 


~ (10) 


277 


■? 


(6) 


337 


(8) 


377 


DEL (11) 
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Notes 

1. Space forward one position 

2. Terminal usage - erase previous character 

3. £ in British use 

4. Apostrophe/single quote 

5. Comma 

6. Terminal usage - kill line 

7. 1963 standard f; terminal use - logical escape 

8. 1963 standard < 

9. Grave 

10. 1963 standard ESC 

11. Rubout - ignored 
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APPENDIX D 
ERROR MESSAGES 



INTRODUCTION 

Error messages are given in the following order: 

SEG Loader Error Messages 

Loader Error Massages 

Run-Time Error Messages 

Batch Error Massages and Warnings 

In each group errors are listed alphabetically. 

Run-time error messages beginning with a filename, device name, 
UFDname, etc., are alphabetized according to the first word which is 
constant. The user should have no trouble in determining this word 
(the second word in the message). Leading asterisks, etc., are ignored 
in alphabetizing. All run-time errors have been grouped together to 
facilitate lookup by the user. 



January 1980 



APPENDIX D IDR4130 



SEG LOADER ERROR MESSAGES 



BAD OBJECT FILE 

User is attempting co load file which has faulty code. The file 
may not be an object file or it may be rncorrectly compiled. 
Fatal error, the load must be aborted. 



CAN'T LOAD IN SECTORED MODE 

The Loader is attempting to load code in sectored mode which has 
not been compiled in sectored mode. This could arise if trying to 
load a module compiled or assembled in 16S or 32S mode. It is 
unlikely that the average applications programmer will encounter 
this. Fatal error, abort load. 



CAN'T LOAD IN 64V OR 64R MODE 

The Loader is attempting to load code in 64V mode which is not 
compiled in that mode. This would arise if: 

1. A program was compiled in a mode other than 64V. 

2. A PMA module is written in code other than 64V and its mode 
is not specified. 

In case 1, the user should recompile the program. 

In case 2, which the average applications programmer is unlikely 
to encounter, the PMA module must be modified. Fatal error, abort 
load. 



COMMAND ERROR 

An unrecognized command was entered or the filenames/ parameters 
following the command are incorrect. Usually not fatal. 



EXTERNAL MEMORY REFERENCE TO ILLEGAL SEGMENT 

An attempt was made to load a 64R mode program, causing a 
reference to an illegal segment number. Recompile in 64V mode. 
Fatal error, abort load. 
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ILLEGAL SPLIT ADDRESS 

Incorrect use of the Loader's SPLIT command. Segments maybe 
split at '4000 boundaries only (i.e., '4000, '10000, '14000, etc.) 
Not fatal; resplit segment. 



MEMORY REFERENCE TO COMMON IN ILLEGAL SEGMENT 

An attempt was made to load a 64R mode progran wherein COMMON 
would be allocated to an illegal segment number. Recompile in 64V 
mode. Fatal error, abort load. 



NO FREE SEGMENTS TO ASSIGN 

All SEG's segments have been allocated; no more are available at 
present. Use SYMBOL command to eliminate COMMON from assigned 
segments, thus reducing the nunber of assigned segments required. 
(User may need larger version of SEG and PRIMOS) . Fatal error , 
abort load. 



NO ROOM IN SYMBOL TABLE 

Unlikely to occur; no user solution. A new issue of SEG with a 
bigger symbol table is required. Check with analyst. As a 
temporary measure, user may try to reduce number of synbols used 
in program. Fatal error, abort load. 



REFERENCE TO UNDEFINED SEGMENT 

Almost always caused by improper use of the SYMBOL command to 
allocate initialized COMMON. Initialized COMMON cannot be located 
with the SYMBOL command; use R/ SYMBOL or A/SWBOL instead. 



SECTOR ZERO BASE AREA FULL 

Extremely unlikely to occur. Not correctable at applications 
level. Check with analyst. Fatal error, abort load. 



SEGMENT WRAP AROUND TO ZERO 

An attempt has been made to load a 64R mode program. The program 

has exceeded 64K and is trying to be loaded over code previously 

loaded. Recompile in 64V mode. Fatal error, abort load. 
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LOADER ERROR MESSAGES 



ALREADY EXISTS ! 

An attempt is being made to define a new symbol; however, the 
symbol name is already a defined symbol in the symbol table. 



BAD OBJECT FILE 

The object text is not recognizable. This usually occurs when an 
attempt is made to load source code or when the object text was 
compiled or assembled for segmented loading. 



BASE SECTOR FULL 

All locations in the sector zero base area have been used. Use 
the AU command to generate base areas at regular intervals, or use 
the SETB or LOAD commands to specifically place base areas. 



CAN'T DEFER COMMON, OLD OBJECT TEXT 

The Defer Common command has been given and a module created with 
a pre-Rev.14 compiler or assembler has been encountered. It is 
not possible to defer Common in this case. The module must be 
recreated with a Rev. 15 compiler or assembler. 



CAN'T - PLEASE SAVE 

The Execute command has been given for a run file which has 
required virtual loading. SAve the runfile and give the Execute 
command . 



CM$ 



Command line error. Unrecognized command given. Not fatal. 



COMMON OUT OF REACH 

Common above '100000 is out of reach of the current load mode 
(16S, 32S or 32R) . Use the MCde command to set the load mode to 
64R. 
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COMMON TOO LARGE 

Definition of this common block causes common to wrap around 
through zero. Moving the top of common - with the common command 
- may help. 



sname ILLEGAL COMMON REDEFINITION 

An attempt is being made to redefine Common block sname to a 
longer length. The user's program should be examined for 
consistent Common definitions. At the very least the longest 
definition for a Common block should be first. 



xxxxxx MULTIPLE INDIRECT 

A module loading in 64R mode requires a second level of 
indirection at location xxxxxx . This message usually results when 
an attempt is made to load code compiled or assembled for 32R mode 
in 64R mode. It can also happen if code has accidentally been 
loaded into base areas as the result of a bad load command 
sequence . 



sname xxxxxx NEED SECTOR ZERO LINK 

At location xxxxxx a link is required for desectoring the 
instruction. No base areas are within reach except sector zero. 
The last referenced symbol was sname . This message is only 
generated when the SZ command has been given. Sname may be the 
name of a Common block, the name of the routine to which the link 
should be made, or the name of the module being loaded. 



XXXXXX NO POST BASE AREA, OLD OBJECT TEXT 

A post base area has been specified for module which was created 
with a pre-Rev.14 compiler or assembler. No base area is created. 
Recreate the object text with a Rev. 15 compiler or assembler. 
This is not a fatal error. 



PROGRAM-COMMON OVERLAP 

The module being loaded is attempting to load code into an area 
reserved for Common. Use the loader's common command to move 
Common up higher. 
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PROGRAM TOO LARGE 



The prog ran has loaded into the last location in memory and has 
wrapped around to load in Location 0. The program size must be 
decreased. Alternatively, compile in 64V mode and use SEG. 



REFERENCE TO UNDEFINED CONMON 

An attempt is being made to link to a Common name which has not 
been defined. This usually happens to users creating their own 
translators. 



SECTORED LOAD MODE INVALID 

A module compiled or assembled to load in R mode has been loaded 
in S mode. Use the MOde command to reset the load mode. It might 
be a good idea to be sure that all modules are correctly written, 
since the default load mode is 32R. 



SYMBOL NOT FOUND 

An attempt is being made to equate two symbols with the SYmbol 
command and the old symbol does not exist. 



SYMBOL TABLE FULL 

The symbol table has expanded down to location '4000. The last 
buffer cannot be assigned to the symbol table. Rebuild LOAD to 
load in higher memory locations, or reduce the nunber of symbols 
in the load. 



SYMBOL UNDEFINED 

An attempt is being made to equate two symbols; however, the old 
symbol is an undefined symbol in the symbol table. 

64R LOAD MODE INVALID 

A module compiled or assembled to run in only 32K of memory is 
being loaded in 64R mode. Recompile or reassemble or change the 
load mode with the loader's MOde command. 
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RUN-TIME ERROR MESSAGES 



ACCESS VIOLATION 64V mode 

Attempt to perform operations in segments to which user has no 
right. 



****AD R-mode function 

Overflow or underflow in double-precision addition/subtraction 
(A$66,S$66) . 



All file units in use. File System 

User has requested use of a file unit when he already has the 
maximum allowable number of file units open. [E$FUIU] 



ALL REMOTE UNITS IN USE File System 

Attempt made to assign a remote unit when none are available. 
(Network error) [E$FUIU] 



**** ALOG*ALOG 10 - ARGUMENT <=0 V-mode function 

Argument not greater than zero used in logarithm (ALOG, ALOG 10) 
function. 



filename ALREADY EXISTS Old file call 

Attempt to create a file or UFD with the name of one already 
existing. [CZ] 



Already exists. File System 

Attempt made to create, in the UFD, a sub-UFD with the same name 
as one already existing. (CREA$$) [E$EXST] 



****AT R-mode function 

Both arguments are zero in the ATAN2 function. 

**** ATAN2 - BOTH ARGUMENTS = V-mode function 

Both arguments are zero in the ATAN2 function. 
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**** ATTDEV - BAD UNIT V-mode call 

Incorrect logical device unit number in the ATTDEV subroutine 
call. 



BAD CALL TO SEARCH Old file call 

Error in calling the SEARCH subroutine t e.g., incorrect parameter. 
[SA] 



Bad command format PRIMOS 

User has issued an illegal command line. Command is ignored. 
[E$CMND] 



BAD DAM FILE Old file call 

The DAM file specified has been corrupted - either by the 
programmer or by a system problem. [SS] 



Bad DAM file. File System 

The DAM file specified has been corrupted - either by the 
programmer or by a system problem. (PRWF$$, SRCH$$) . [E$BDAM] 

Bad key in call . File System 

Incorrect key value specified in subroutine argument. (ATCH$$, 
RDEN$$, SATR$$, SRCH$$, SGDR$$) [E$BKEY] 



BAD PARAMETER Old file call 

Incorrect parameter value in subroutine call. [SA] 

Bad parameter. PRIMOS 

Incorrect parameter value in subroutine call. [E$BPAR] 
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BAD PASSWORD Old file call 

Incorrect password specified in ATTACH subroutine. Returns to 
FRIMOS level attached to no UFD. [AN] 



Bad password. File System 

Incorrect password specified in ATCH$$ subroutine. Returns to 
FRIMOS level attached to no UFD. [ATCH$$] [E$BPAS] 



Note 

To protect UFD privacy the system does not allow the 
user to trap BAD PASSWORD errors. 

BAD RTNREC PRIMOS 

System error. 



Bad segment dir unit. File System 

Error generated in accessing segment directory, i.e., FRIMOS file 
unit specified is not a segment directory. (SRCH$$) [E$BSUN] 



Bad stack format. PRIMOS 

Bad stack format signalling. 

Condition mechanism cannot perform requested action because the 
command processor stack has been damaged (system error) . User is 
returned to PRIMOS command level. [E$STKF, E$STKS] 



BAD SVC PRIMOS 

Bad supervisor call. In FORTRAN usually caused by program writing 
over itself. 



Bad truncate of segment dir. File System 

Error encountered in truncating segment directory. (SGDR$$) 
[E$BTRAN] 



Bad unit number. File System 

PRIMOS file unit number specified is invalid - outside legal 
range. (PRWF$$ f RDEN$$, SRCH$$, SGDR$$) . [E$BUNT] 
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Bad use of exit. PRIMOS 

The condition mechanism sends this fatal message. User is 
returned to PRIMOS command level. [E$NEXP] 



Beginning of file. File System 

Attempt was made to access locations before the beginning of the 
file. (PRWF$$, RDEN$$, SGER$$) [E$BOF] 



****BN n R-mode function 

Device error in REWIND command on FORTRAN logical unit n. 

Buffer too small. File System 

Buffer as defined is not large enough to accomodate entry to be 
read into it. (RDEN$$) [E$BFTS] 

Command line truncated. PRIMOS 

An illegal command line has been received. The command is not 
executed, and the user is returned to PRMOS command level. 
[E$TRCL] 

Concealed stack overflow. PRIMOS 

System error. (Generally sent by the condition mechanism.) 
[E$CSOV] 

Crawlout unwind failed. PRIMOS 

System error. (Generally sent by the condition mechanism.) 
[E$CRUN] 

**** DATAN - BAD ARGUMENT V-mode function 

The second argument in the DATAN 2 function is zero. 

****DE R-mode function 

The exponent of a double-precision number has overflowed. 
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The Device is in use. File System 

Attempt was made to ASSIGN a device currently assigned to another 
user . [E$DVIU] 



Device not assigned. File System 

Attempt was made to perform I/O operations on a device before 
assigning that device. [E$NASS] 



Device is not started. File System 

Attempt was made to access a disk not physically or logically 
connected to the system. If disk must be accessed, systems 
manager must start it up. [E$DNS] 



**** DEXP - ARGUMENT TOO LARGE V-mode function 

The argument of the DEXP function is too large; i.e., it will 
give a result outside the legal range. 

**** DEXP - OVERFLCW*UNDERFLCW V-mode function 

An overflow or underflow condition occurred in calculating the 
DEXP function. 

The directory is damaged. File System 

UFD has become corrupted. (ATCH$$, CREA$$, GPAS$$, RDEN$$ 

SATR$$, SRCH$$) [E$BUFD]. Calls to RDEN$$ return this as a 

trappable error; other commands return to the FRIMOS command 
level. 

The directory is not empty. File System 

Attempt was made to delete a non-empty directory. (SRCH$$) 
[E$DNTE] 

DISK FULL Old file call 

No more roan for creating/extending any type of file on disk. 
[DJ] 
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The disk is full. File System 

No more room for creating/extending any type of file on disk. 
(CREA$$, PRWF$$, SRCH$$, SGDR$$) . [E$DKFL] 



Note 

Space may be made available. Use the internal PRIMOS 
commands ATTACH, LISTF, and DELETE to remove files which 
are no longer needed. 

Disk 1*0 Error File System 

A read/write error was encountered in accessing disk. Returns 
immediately to PRIMOS level. Not correctable by applications 
progranmer. (ATCH$$, CREA$$, GPAS$$, PRWF$$, RDEN$$ f SATR$$, 
SRCH$$, SGDR$$). [E$DISK] 

Disk is write- protected. File System 

An attempt has been made to write to a disk which is 
WRITE-protected . [E$WTPR] 

DK ERROR Old file call 

A read/write error was encountered in accessing disk. [VB] 

****DL R-mode function 

Argument was not greater than zero in DLOG or DL0G2 function. 

**** DL0G*DL0G2 - ARGUMENT <=0 V-mode function 

Argument not greater than zero was used in DLOG or DLOG 2 function. 

****DN n R-mode function 

Device error (end of file) on FORTRAN logical unit n. 

**** DSIN*DC0S - ARGUMENT RANGE ERROR V-mode function 

Argument outside legal range for D3IN or DCOS function. 
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**** ESQRT - ARGUMENT <0 V-mode function 

Negative argument in E60RT function. 

****DT R-mode function 

Second argument is zero in DATAN2 function. (D$22) 

DUPLICATE NAME Old file call 

Attempt to create/rename a file with the name of an existing file. 
[CZ] 

****DZ R-mode function 

Attempt to divide by zero (double- precision) . 

End of file. r File System 

Attempt to access location after the end of the file. (PRWF$$, 
RDEN$$, SGDR$$) [E$EOF] 

****EQ R-mode function 

Exponent overflow. (A$8l) 

****EX R-mode function 

Exponent function value too large in EXP or DEXP function. 

**** EXP - ARGUMENT TOO LARGE V-mode function 

The argument of the EXP function is too large, i.e., it will give 
a result outside the legal range. 

**** EXP - OVERFLOW V-mode function 

Overflow occurred in calculating the EXP function. 

Fatal error in crawlout. PRIMOS 

System error. [E$CRWL] 
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****FE R-mode function 

Error in FOFMAT statement. FORMAT statements are not completely 
checked at compile time. (F$IO) 

File in use. File System 

Attempt made to open a file already opened or to close/delete a 
file opened by another user, etc. (SRCH$$) [E$FDEL] 

FILE OPEN ON DELETE File System 

Attempt made to delete a file which is open. (SRCH$$) [E$FDEL] 

The file is too long. File System 

Attempt made to increase size of segment directory beyond size 
limit. (SGDR$$) [E$FITB] 

****FN n R-mode function 

Device error in BACKSPACE command on FORTRAN logical unit n. 

**** F$BN - BAD LOGICAL UNIT V-mode function 

FORTRAN logical unit number out of range. 

**** f$FLEX - DOUBLE-PRECISION DIVIDE BY ZERO 64V mode 

Attempt has been made to divide by zero. 

**** f$flex - DOUBLE-PRECISION EXPONENT OVERFLOW 64V mode 

Exponent of a double- precision number has exceeded maximum. 

**** p$FLEX - REAL => INTEGER CONVERSION ERROR 64V mode 

Magnitude of real number too great for integer conversion. 

**** F$FLEX - SINGLE-PRECISION DIVIDE BY ZERO 64V mode 

Attempt has been made to divide by zero. 
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**** F$FLEX - SINGLE-PRECISION EXPONENT OVERFLOW 64V mode 

Exponent of a single- precision nunber has exceeded maximum. 

**** F$IO - FORMAT ERROR V-mode function 

Incorrect FORMAT statement. FORMAT statements are not completely 
checked at compile time. 

**** F$IO - FORMAT*DATA MISMATCH V-mode function 

Input data does not correspond to FORMAT statement. 

**** F$IO - NULL READ UNIT V-mode function 

FORTRAN logical unit for READ statement not configured properly. 

****II R-mode function 

Exponentiation exceeds integer size. (E$ll) 

ILLEGAL INSTRUCTION AT octal-location R mode and 64V mode 

An instruction at octal- location cannot be identified by the 
computer . 

Illegal name. F i le system 

Illegal name specified for a file or UFD. (CREA$$, SRCH$$) 
[E$BNAM] 

Illegal remote reference. File System 

Attempt to perform network operations by user not on network. 
[E$IREM] 

ILLEGAL SEGNO 64V mode 

Program referenced a non-existent segment or a segment number 
greater than those available to the user. 
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Illegal treename. File System 

The string specified for a treename is syntactically incorrect. 
[E$ITRE] 

****im R-mode function 

Overflow or underflow occurred during a multiply. (M$ll, E$ll) 

filename IN USE Old file call 

Attempt made to open a file already opened, or to close/delete a 
file opened by another user, etc. [SI] 

Insufficient access rights. File System 

User does not have access right to file, or does not have write 
access in a UFD when attempting to create a sub-UFD. (CREA$$, 
GPAS$$, SATR$$, SRCH$$, SGDR$$) [E$NRIT] 

Invalid argument to command. PRIMOS 

A command has been issued with an illegal argument. The command 
is not executed. [E$BARG] 

Invalid segment number. File System 

Attempt made to access segment number outside valid range. 
[E$BSGN] 

**** 1**1 _ ARGUMENT ERRCR V-mode function 

Exponentiation exceeds integer size. 

****LG R-mode function 

Argument not greater than zero in ALOG or ALOG10 function. 

Max number of users exceeded. PRIMOS 

The maximum allowable number of users are already using the 
system. (This may mean that the operator has used the MAXUSR 
command to decrease the number of users temporarily.) 
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Max remote users exceeded. File system 

No more users may access the network. [E$TMRU] 

Name is too long. File System 

Length of name in argument list exceeds 32 characters. [E$NMLG] 

NO AVAILABLE SEGMENTS 64V mode 

Additional segment(s) required - none available. User should log 
out to release assigned segments and try again later. 

No phantoms are available. File system 

An attempt has been made to spawn a phantom. All configured 
phantoms are already in use. [E$NPHA] 

No on- unit found. Condition mechanism 

Condition mechanism cannot take action. User is returned to 
ERIMOS command level. [D$NO0N] 

No room. File System 

An attempt has been made to add to a table of assignable devices 
with a DISKS or ASSIGN AMLC command and the table is already 
filled. [E$RO0M] 

No timer. File System 

Clock not started. System error. [E$NTIM] 

NO UFD ATTACHED Old file call 

User not attached to a UFD [AL f SL] . Usually occurs after attempt 
to attach with a bad password. 

No UFD attached. File System 

User not attached to a UFD. (ATCH$$, CREA$$, GPAS$$ f SATR$$, 
SRCH$$) . [E$NATT] Usually occurs after attempt to attach with a 
bad password. 
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NO VECTOR R and 64V mode 

User error in program has caused PRIMOS to attempt to access an 
unloaded element. 

1. A UII, P3U, or FLEX to location 

2. Trap to location 

3. SVC switch on, SVC trap and location '65 is 0. 

Not a segment directory. File System 

Attempt to perform segment directory operations on a file which is 
not a segment directory. (SRCH$$) [E$NTSD] 

NOT A UFD. Old file call 

Attempt to perform UFD operations on a file which is not a UFD. 
[AR] 

Not a UFD File System 

Attempt to perform UFD operations on a file which is not a UFD. 
(ATCH$$, GPAS$$, SRCH$$). [E$NTUD] 

device-name NOT ASSIGNED PRIMOS 

User program has attempted to access an I/O device which has not 
been assigned to the user by a PRIMOS command. 

filename NOT FOUND Old file call 

File specified in subroutine call not found. [AH, SH] 

filename NOT FOUND File System 

File specified in subroutine call not found. (ATCH$$, GPAS$$ f 
SATR$$, SRCH$$) [E$FNTF] 

filename not found in segment dir. File System 

Filename specified in subroutine call not found in specified 
segment directory. (SRCH$$, SGDR$$) [E$FNTS] 
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NULL READ UNIT PRIMOS 

Program has attempted to read with a bad unit nunber. This may be 
caused by the program overwriting itself (array out of bounds) . 



OLD PARTITION File System 

Attempt to perform, in an old file partition, an operation 
possible only in a new file partition; e.g., date/time 
information access. (SATR$$) [E$OLDP] 

Operation illegal on directory. PRIMOS 

User has tried to perform an operation on a directory that is not 
allowed (such as editing it) . [E$DIRE] 

****p A n R-mode function 

PAUSE statement n (octal) encountered during program execution. 

**** PAUSE n V-mode function 

PAUSE statement n (octal) encountered during program execution. 

POINTER FAULT 64V mode 

Reference has been made to an argument or instruction not in 
memory. The two usual causes of this are an incomplete load 
(unsatisfied references) , or incomplete argument list in a 
subroutine or function call. 

Pointer mismatch found. PRIMOS 

Internal file pointers have become corrupted. No user remedial 
action possible. System Administrator must correct. [E$PTRM] 

PROGRAM HALT AT octal- location R mode and 64V mode 

Program control has been lost. The program has probably written 
over itself or the load was incomplete (R-mode) . 

PRWFIL BOF Old file call 

Attempt by PRWFIL subroutine to access location before beginning 
of file. [PG] 
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PRWFIL EOF cad file call 

Attempt by PRWFIL subroutine to access location after end of file. 
[PE] 



PRWFIL POINTER MISMATCH Old file call 

The internal file pointers in the PRWFIL subroutine have become 
corrupted . 



PRWFIL UNIT NOT OPEN Old file call 

The PRWFIL subroutine is attempting to perform operations using a 
PRIMOS file unit number on which no file is open. 



PTR MISMATCH File System 

Internal file pointers have become corrupted. No user remedial 
action possible. (ATCH$$, CREA$$, GPAS$$, PRWF$$, RDEN$$, SATR$$, 
SRCH$$, SGDR$$). Consult system manager. 



The remote line is down. File System 

Remote call-in access to computer not enabled. [E$RLDN] 

**** RI R-mode function 

Argument is too large for real- to- integer conversion. (C$12) 

****RN n R-mode function 

Device error or end-of-file in READ statement on FORTRAN logical 
unit n. 

****SE R-mode function 

Single precision exponent overflow. 

SEG^DIR ER Old file call 

Error encountered in segment directory operation. [SQ] 
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Segment directory error. PRIMOS 

Error encountered in segment directory operation. [SQ] [E$SDER] 

Segdir unit is not open. File System 

Attempt has been made to reference a segment directory which is 
not open. (SRCH$$) [E$SUNO] 

Semaphore overflow. File System 
System error. [E$SEMO] 

**** SIN*COS - ARGUMENT TOO LARGE Vnmode function 

Argument too large for SIN or COS function. 

****SQ R-mode function 

Negative argument in SORT or DSQRT function. 

**** SQRT - ARGUMENTS V-mode functon 
Negative argunent in SQRT function. 

****ST n R-mode function 
STOP statement n (octal) encountered during program execution. 

**** STOP n V-mode function 
STOP statement n (octal) encountered during program execution. 

****SZ R-mode function 
Attempt to divide by zero (single-precision) . 

Stack overflow in crawlout. PRIMOS 
System error. [E$CROV] 
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Too many subdirectory levels. File System 

Attempt to create more than 72 levels of sub-UFDs. This error 
occurs only on old file partitions; new file partitions have no 
limit on UFD levels. [E$TMUL] 



UFD FULL Old file call 

No more room in UFD. [SK] 

The UFD is full. File System 

UFD has no rocm for more files and/or sub-UFD's. Occurs only in 
old file partitions. (CREA$$, SRCH$$) [E$FDFL] 

UFD OVERFLOW Old file call 

No more room in UFD. 

Unable to find fault frame. Condition mechanism 

A call was made to CNSIG$, but CNSIG$ could not find that any 
condition had been raised. 

UNIT IN USE Old file call 

Attempt to open file on FRIMOS file unit already in use. [SI]. 

Unit in use. File System 

Attempt to open file on PRIMOS file unit already in use. 
(SRCH$$) . [E$UIUS] 

UNIT NOT OPEN Old file call 

Attempt to perform operations with a file unit number on which no 
file has been opened. [PD, SD] 

Unit not open. File System 

Attempt to perform operations with a file unit number on which no 
file has been opened . (PRWF$$, RDEN$$, SRCH$$, SGER$$) . [E$UNOPl 
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UNIT OPEN ON DELETE Old file call 

Attempt to delete file without having first closed it. [SD] 

****WN n R-mode function 

Device error or end-of-file in WRITE statement on FORTRAN logical 
unit n. 

****XX R-mode function 
Integer argument >32767. 
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BATCH WARNINGS AND MESSAGES 



Bad $$ conmand. 

(Fatal) A command file was submitted using the JOB command that had 
a $$ line other than the $$ JOB line as the first non-comment line. 
The command file should be changed so that the "$$" line is legal. 
The use of $$ is reserved for future expansion by BATCH. 



(Changes made) 

(Response) The changes specified in a JOB -CHANGE operation have 
been made. If the job is initiated after the changes are made, 
then it will execute with the specified changes in place. The job 
status will be displayed after the above message is typed out. 



Command file required as first argument on submission. 

(Fatal) The JOB command was given with job options (such as -HOME, 
-PRIORITY, -CPTIME, etc.) but no command file was seen before 
those options. The syntax is "JOB pathname [-options']". 

Cpu limit must be specified. 

(Fatal) The queue referred to by a -QUEUE option during job 
submission is defined such that the -CPTIME option is a required 
parameter (i.e., default CPU limit for that queue is greater than 
the maximum CPU limit for that queue). The job should be 
resubmitted with the -CPTIME option specified. To determine the 
maximum limits for queues, use BATGEN -DISPLAY. 



Elapsed time limit must be specified. 

(Fatal) The queue referred to by a -QUEUE option during job 

submission has a default elapsed time limit greater than its 

maximum time limit. Resubmit the job with the -ETIME option 
specified. 



End of line. 

(Fatal) One of the Batch programs was expecting to find more 
information on the command line, but end-of-line was found instead. 
The message will generally contain more information on what was 
expected. Re-enter the command with the additional requested 
information. 
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End of line. Illegal <option> argument 

(Fatal) One of the job parameter options specified on the JOB 
command line had no argument. The information required by that 
option should be supplied when the command is re-entered. 

Home ufd required. 

(Fatal) The -HOME option was not present on the JOB or the 
(optional) $$ JOB line during submission, and the program was 
unable to determine the home attach point of the submitting job. 
Resubmit the job, and include the -HOME option followed by the 
absolute pathname of the UFD where the job is to execute. If the 
pathname cannot fit, use a shorter version of it when you resubmit 
the command file, after editing the file to include an "ATTACH" 
command that descends the remaining sub-ufds to reach the 
destination. 



Home=< pa thname> 

(Response) During job submission, the -HOME option was not 
specified on the command line or in the command file ($$ JOB) , so 
the JOB command determined the home attach point of the submitting 
job. This message is typed out to remind the user that the -HOME 
option was not specified. The job did successfully submit, 
however. 



Illegal -CHANGE option. 

(Fatal) The options -QUEUE and -PRIORITY are illegal during a 
-CHANGE operation using the JOB command, as queue and queue 
priority of a job cannot be changed. Cancel or abort the job and 
resubmit it into the appropriate queue with the desired queue 
priority. 



Illegal combination. <option> 

(Fatal) A job parameter (such as -ACCT, -HOME or -QUEUE, etc.) was 
specified on the same JOB command line as an option to perform an 
action (such as -CANCEL, -DISPLAY, -ABORT, etc.) . Use separate JOB 
commands to perform separate functions. 



Illegal limit. 

(Fatal) The parameters supplied to the -CPTIME or -ETIME options 
during job submission/changing were not legal limits, i.e. they 
were less than or equal to 0, or were not legal decimal numbers and 
not the string "None". Re-enter the command with legal limits. 
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Illegal name. 

(Fatal) One of the Batch programs was expecting a name or command, 
but it read an unquoted token beginning with a dash ('-') , 
indicating that an option was present. 

Illegal number. <text> (JOB) 

(Eatal) The argument for the -FUNIT or -PRIORITY option during job 
submission using the JOB command was not a legal decimal number. 
Re-enter the command line with legal numeric parameters. 



Illegal option. 

(Fatal) One of the Batch programs was expecting an option, i.e., an 
unquoted token beginning with a dash ('-'). Re-enter the command 
line with a legal format. 



Illegal queue name. <text> (JOB) 

(Fatal) The queue name specified after a -QUEUE option while 
submitting or changing a job did not comply with queue name format 
rules. Use BATGEN -STATUS or -DISPLAY to determine the names of 
legal queues. 



Incorrect user-name. 

(Fatal) A command file was submitted using the JOB command that had 
a $$ JOB line as the first non-comment line, but the user-name 
specified after the "JOB" specifier did not match the user-name of 
the submitting user. Edit the command file and change the 
user-name in the $$ JOB line to the user-name of the submitter. 



*** Invalid batch database, please contact your system administrator. 

(Severe) The running job detected an error (such as disk failure, 
pointer mismatch, or misprotected file) in the Batch system 
database. It will flag the database as invalid. Notify the System 
Administrator, who has the responsibility for re-initializing the 
database (or running *FIXBAT or FIXRAT as the case may be) . The 
BATCH and JOB commands will be inoperative until the situation is 
resolved. 



<nn> is out of range. <option> 
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(Fatal) The numbers supplied as parameters to the -FUNIT or 
-PRIORITY options during job submission/ changing were out of range. 
The range for -FUNIT is from 1 to 126; that for -PRIORITY is frcm 
to 9. The job should be resubmitted or changed with legal -FUNIT 
and -PRIORITY values. Note that the system may be configured to 
have fewer than 126 units per user at cold-start, and the -FUNIT 
argument will be limited to the maximum configured unit number. 



?JOB < ex tnam> ( < intnam> ) < sta tus> . 

(Warning) An attempt was made to perform an operation on a job 
using the JOB command that could not be performed because of its 
status: for example, trying to restart a completed job. 



Job name required. 

(Fatal) The options -CHANGE, -CANCEL, -ABORT, -RESTART, -HOLD and 
-RELEASE all require a job identifier (internal or external name) . 
Re-enter the command with the job id. (For example: "JOB C.TOP 
-HOLD" , "JOB #10032 -ABORT") . 



Job not found. 

(Fatal) The job referred to in a JOB command such as -CHANGE, 
-CANCEL, -ABORT, -RESTART, -HOLD or -RELEASE, could not be found by 
searching the active jobs list. This could mean one of three 
things: that no job exists with that name, that all jobs that have 
that name are not active jobs (i.e., have completed, aborted or 
been cancelled) , or that a job exists with that external name but 
the user making the request is not the same user that originally 
submitted the job. 



(Job no longer restartable) 

(Response) A JOB -CANCEL was performed on an executing job. The 
job itself is not cancelled; it has been flagged as being 
unrestartable (i.e., a -RESTART will abort the job but not restart 
it) . 



(Job not restartable) 

(Warning) A JOB -RESTART was performed on a job that had been 
flagged as unrestartable. An attempt will be made to abort the 
job. 



(Job restarted) 
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(Response) A JOB -RESTART was performed on a job, and the job has 
been flagged as restartable. Although an error message may appear 
after this message, the job will generally be restarted unless a 
JOB -CANCEL or JOB -CHANGE -RESTART NO is done on it. Possible 
errors after this message include "Insufficient access rights" if 
the user is logged in as SYSTEM, and restarted another user* s job 
from a user terminal (not the supervisor terminal) , or if the 
process recently logged out. "Not found" may also be returned in 
this case. 



*** Jobs are not being processed at this time. 

(Severe) If followed by "*** Please contact your system 
administrator immediately", it indicates that the Batch database 
has not been initialized, or that something has happened to it 
(like a disk head crash) . If followed by "*** Please try again 
later", it indicates that while the database is still valid, the 
Batch monitor was logged out using a method other than "BATCH 
SYSTEM -STOP", and will verify the validity of the database when it 
is started up. Either way, the user will be immediately returned 
to command mode (i.e., the operation the user attempted will not be 
performed) . This can be typed out by the BATCH or the JOB commands 
when they start running. 



Multiple jobs with this name (use internal name) . 

(Fatal) A reference was made to a job using a filename in the JOB 
command, and there were at least 2 such jobs belonging to the user 
making the reference that were active. The job- id must be used in 
this case. Use JOB -STATUS ALL to determine the filenames and 
job- ids of all jobs belonging to the user issuing the command. 

Multiple occurance. 

(Fatal) An option was specified twice during job submission or job 

changing (example: JOB C TEST -HOME HERE -HOME THERE) on either 

the JOB or $$ JOB line. (If the option is specified once on the 
JOB line and once on the $$ JOB line, no error will result and the 
parameter on the JOB line will take precedence) . Re-enter the 
command, specifying each option only once. 



Must be first option. 

(Fatal) The options -CHAN3E, -CANCEL, -ABORT, -RESTART, -STATUS, 
-DISPLAY, -HOLD and -RELEASE must be the first option on the JOB 
command line (after a sometimes optional job identifier) . Use the 
JOB command several times to perform several operations. 
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No active jobs [named "<jobname>"] for user <username>. 

(Response) There are no jobs belonging to that user that are 
waiting, held, or executing. 

The jobname is output if a jobname was specified for the -DISPIAY 
or -STATUS command; otherwise it is emitted. 



No job changes specified. 

(Fatal) The -CHANGE option was given to the JOB command, but no 
actual changes were specified on the command line. Specify changes 
to be made after the -CHANGE option. 

No jobs [named "<jobname>"] for user <username>. 

(Response) This message is typed out by a JCB -DISPLAY ALL or 
-STATUS ALL command, and indicates that there are no jobs belonging 
to that user. 



No longer executing. 

(Fatal) A JOB -ABORT or JOB -RESTART was performed on a job that 
had execution status, but by the time the execution file was read 
in to determine the user nunber of the process, it had disappeared. 
If the message "(Job restarted)" had been typed out, then the job 
would be restarted. 



No queue available for job. 

(Fatal) A job was submitted using the JOB command that did not use 
the -QUEUE option to specify the queue to which it was to be 
submitted, and no suitable queue could be found. Suitability for a 
queue includes CPU and elapsed time limits being within the 
confines of the queue, queue being unblocked, etc. Use the BATGEN 
-STATUS or -DISPLAY command to yield a list of legal queues and 
their status. 



No queues have waiting or held jobs. 

(Response) A BATCH -DISPLAY command was issued, and there were no 
queues that had any waiting or held jobs in them. A queue may have 
one executing job in it, but an executing job is not considered a 
waiting or held job. 



No recent jobs [named <jobname>"] for user <username>. 
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(Response) There are no jobs belonging to that user (or in the 
batch system if the user is SYSTEM that were submitted, initiated, 
aborted, completed or cancelled today. 



No running jobs. 

(Response) A BATCH -DISPLAY command was issued, and there were no 
jobs that were currently running. It is possible for there to be 
no running jobs and to have jobs waiting, however, even when the 
monitor is running and there are free phantoms; there is always a 
small amount of turnaround time between the submittal of a job and 
the execution of a job. 



Not an absolute treename. 

(Fatal) The home ufd specified with the -HOME option during 
submission using the JOB command (or changing of job parameters) 
was a relative (pathname) , i.e., it began with "*>". Re-submit the 
job, giving an absolute pathname after the -HOME option. 



Not your job. 

(Fatal) A reference was made to a job using an internal name in the 
JOB command, and the referenced job did not belong to the user 
making the reference. Use "JOB -STATUS ALL" to obtain a list of 
all jobs belonging to the user making the request. 



Null home ufd. 

(Fatal) The home ufd specified with the -HOME option during 
submission using the JOB command (or changing of job parameters) 
was a null string. Re-submit the job with an absolute pathname 
after the -HOME option. 



Please stand by. 

(Response) This message and others like it ("File in use, please 
stand by") will be output if the program being run is trying to 
gain access to a file that is in use for more than 5 seconds. 
After 20 seconds, the "File is use..." message will be output, and 
after 30 seconds, the message "Timeout of 30 seconds has occurred" 
will be output and the program will "give up". Usually this will 
result in a fatal error, as it could indicate that system security 
is broken. 



Please wait. 
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(Response) This message asks that the user be patient because the 
program he is running has been locking up the Batch database too 
long and is not allowing other processes to have access to it. It 
is not a fatal error. It generally only is output when a system is 
heavily loaded, or when the current process has a very low priority 
and does not run frequently. 

Queue blocked. 

(Fatal) The queue referred to by a -QUEUE option during job 
submission is currently blocked to new submissions. Try it again 
later, or use another queue. 



Queue deleted. 

(Fatal) The queue that the job was being submitted to was present 
when it was first checked out, but by the time the command file had 
been copied and some other activities had taken place, the queue 
had been deleted. The job should be resubmitted to a different 
queue. 



Queue does not exist. 

(Fatal) The -QUEUE option on the JOB command line or the (optional) 
$$ JOB line referred to a queue that either did not exist or was in 
the process of being deleted ("flagged for deletion"! . The BATGEN 
-STATUS or -DISPLAY command should provide a list of currently 
available queues and their status, if the file that defines queues 
is accessible by users. 



Queue full. 

(Fatal) There are already 10,000 jobs (whether active or inactive) 
in the queue to which the job is being submitted. The queue must 
be deleted and re-created before more jobs can be submitted to it. 
The system administrator should be asked to do this. Meanwhile, if 
any other queues are available, they can be used instead by the 
user. 



Register setting. 

(Fatal) Register settings are illegal in the Batch subsystem 
(except as part of a submitted command file) . Re-enter the command 
line without the register setting. 



Searching for free command file, please stand by. 
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(Response) This and other messages like "Queue is in heavy 
use... please stand by" mean that many users are submitting command 
files at once. The situation should resolve itself in a short 
amount of time. 



Specified value is out of range. 

(Fatal) The -CPTIME or -ETIME option specified during job 
submission or a -CHANGE operation is greater than the maximum 
allowed by the queue to which the job was submitted. This message 
will be preceded by a message indicating the maximum limit for that 
queue ("Cpu limit is xx" or "Elapsed time limit is xx") . If the 
limits cannot be lowered and the job successfully run, then try a 
queue with higher limits. 

Syntax error. Register settings are illegal 

(Warning) This message is output if end-of-line is expected and a 
register setting is found instead. Re-enter the command without 
register settings. 



<text> seen when end-of-line expected. 

(Fatal) <text> was seen when there should have been no more text 
(end of line) . The command will be ignored and the user will be 
returned to PRIMOS level. 



This job cannot be restarted. 

(Response) Output by a JOB -DISPLAY command if the job being 
displayed has had a JOB -CANCEL done to it while it was executing, 
or was submitted with the -RESTART NO option. Any -RESTARTS done 
to the job will abort the job (if they succeed) , but the job will 
not be restarted. 

(This job has already executed nn time(s)) . 

(Response) Output by a JOB -DISPLAY command if the job being 
displayed is executing and has already been executed. This is the 
result of a JOB -RESTART being done on that job, or a system 
cold-start after being brought down while the job was executing. 

Too many options. 

(Fatal) At least two options were entered that conflicted with each 
other, such as JOB -DISPLAY -CHANGE or JOB C_TEST -ABORT -CANCEL. 
Use separate JOB commands to perform separate operations. 
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Unknown option. 

(Fatal) An option was entered to the BATCH or JOB command that was 
not recognized. 

Warning: jobs are not being processed at this time. 

(Response) The Batch monitor is not running. No submitted jobs 
will be executed until it has been started up. The operation 
requested will then be performed. If the monitor is force-logged 
out, or the system is shut down without the monitor logging itself 
out, there may be a database problem as a result. 
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